Files
vibemake-pcb-studio/eeschema/remote_symbol_import_utils.ts
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

335 lines
10 KiB
TypeScript

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* `eeschema/remote_symbol_import_utils.{h,cpp}` (KiCad 10): the pieces a
* remote symbol import is built from — file-name sanitising, the library
* prefix and destination from `eeschema.json`'s `remote_symbols.*`, writing a
* downloaded file, adding its library to a library table, decoding a symbol
* library payload, the local LIB_IDs of a bundle's footprints, and placing the
* imported symbol.
*
* The file system is common's mounted one (`wx/filefn.ts`): the destination
* `${KIPRJMOD}/RemoteLibrary` resolves into the project's mount, a directory
* exists as soon as a file is written under it, and `Mkdir` is "a writable
* mount covers this path". `LIBRARY_MANAGER` is not ported, so the library
* tables and the reload come in as a {@link REMOTE_LIBRARY_MANAGER}.
*/
import { ExpandEnvVarSubstitutions } from '@ziroeda/common/common.js';
import { LIB_ID } from '@ziroeda/common/lib_id.js';
import {
type LIBRARY_TABLE,
LIBRARY_TABLE_SCOPE,
type LIBRARY_TABLE_TYPE,
} from '@ziroeda/common/libraries/library_table.js';
import { Pgm } from '@ziroeda/common/pgm_base.js';
import { REMOTE_PROVIDER_SETTINGS } from '@ziroeda/common/remote_provider_settings.js';
import {
MEMORY_FILESYSTEM,
wxCreateTempFileName,
wxFindMount,
wxNormalizePath,
wxRemoveFile,
wxWriteFileSync,
} from '@ziroeda/wx/filefn.js';
import { currentEeschemaSettings } from './eeschema_settings.js';
import { LIB_SYMBOL } from './lib_symbol.js';
import { SCH_IO_KICAD_SEXPR } from './sch_io/kicad_sexpr/sch_io_kicad_sexpr.js';
/**
* `LIBRARY_MANAGER` as the remote import asks it: the table of a type and
* scope, and re-reading one library entry after its table or file changed.
*/
export interface REMOTE_LIBRARY_MANAGER {
Table(aType: LIBRARY_TABLE_TYPE, aScope: LIBRARY_TABLE_SCOPE): LIBRARY_TABLE | null;
ReloadLibraryEntry(
aType: LIBRARY_TABLE_TYPE,
aNickname: string,
aScope: LIBRARY_TABLE_SCOPE,
): void;
LoadLibraryEntry(aType: LIBRARY_TABLE_TYPE, aNickname: string): void;
}
/** `wxIsalnum`: a letter or a digit, in any script (KiCad runs in a UTF-8 locale). */
const isAlnum = (ch: string): boolean => /^[\p{L}\p{N}]$/u.test(ch);
/**
* `SanitizeRemoteFileComponent` (:40-57): trimmed, empty replaced by
* \a aDefault, every character but letters, digits, `_`, `-` and `.` made `_`,
* lower-cased on request.
*/
export function SanitizeRemoteFileComponent(
aValue: string,
aDefault: string,
aLower = false,
): string {
let result = aValue.trim();
if (result === '') result = aDefault;
result = [...result]
.map((ch) => (isAlnum(ch) || ch === '_' || ch === '-' || ch === '.' ? ch : '_'))
.join('');
return aLower ? result.toLowerCase() : result;
}
/** `RemoteLibraryPrefix` (:60-69): the configured prefix (or "remote"), sanitised, lower case. */
export function RemoteLibraryPrefix(): string {
let prefix = currentEeschemaSettings().remote_symbols?.library_prefix ?? '';
if (prefix === '') prefix = REMOTE_PROVIDER_SETTINGS.DefaultLibraryPrefix();
return SanitizeRemoteFileComponent(prefix, 'remote', true);
}
/** `wxFileName::Mkdir( wxS_DIR_DEFAULT, wxPATH_MKDIR_FULL )`: a writable mount covers \a aDir. */
function mkdirFull(aDir: string): boolean {
const hit = wxFindMount(wxNormalizePath(aDir));
return !!hit && hit.mount instanceof MEMORY_FILESYSTEM;
}
/** The directory half of a path (`wxFileName::SetFullName( "" )`). */
const dirOf = (aPath: string): string => aPath.slice(0, aPath.lastIndexOf('/') + 1);
/** `WriteRemoteBinaryFile` (:72-104). */
export function WriteRemoteBinaryFile(
aOutput: string,
aPayload: Uint8Array,
aError: { value: string },
): boolean {
if (aPayload.length === 0) {
aError.value = 'Payload was empty.';
return false;
}
const targetDir = dirOf(aOutput);
if (!mkdirFull(targetDir)) {
aError.value = `Unable to create '${targetDir}'.`;
return false;
}
if (!wxWriteFileSync(aOutput, aPayload)) {
aError.value = `Unable to open '${aOutput}' for writing.`;
return false;
}
return true;
}
/**
* `EnsureRemoteDestinationRoot` (:107-142): the configured destination (or
* `${KIPRJMOD}/RemoteLibrary`), variables expanded against the project,
* created if missing. The directory is returned with a trailing separator.
*/
export function EnsureRemoteDestinationRoot(
aOutDir: { value: string },
aError: { value: string },
): boolean {
let destination = currentEeschemaSettings().remote_symbols?.destination_dir ?? '';
if (destination === '') destination = REMOTE_PROVIDER_SETTINGS.DefaultDestinationDir();
const prj = Pgm().GetSettingsManager().Prj();
destination = ExpandEnvVarSubstitutions(destination, (token) => prj.TextVarResolver(token));
destination = destination.trim();
if (destination === '') {
aError.value = 'Destination directory is not configured.';
return false;
}
// wxFileName::DirName( destination ).Normalize(): a directory, absolute.
const dir = wxNormalizePath(destination.endsWith('/') ? destination : `${destination}/`);
if (!mkdirFull(dir)) {
aError.value = `Unable to create directory '${dir}'.`;
return false;
}
aOutDir.value = dir;
return true;
}
/**
* `EnsureRemoteLibraryEntry` (:145-207): the library \a aNickname in the global
* or project table of \a aTableType, pointing at \a aLibraryPath — updated
* when it points elsewhere, added ("Remote download") when missing, and the
* table saved. With no table, fails only when \a aStrict. \a aManager stands
* for upstream's `Pgm().GetLibraryManager()`.
*/
export function EnsureRemoteLibraryEntry(
aManager: REMOTE_LIBRARY_MANAGER,
aTableType: LIBRARY_TABLE_TYPE,
aLibraryPath: string,
aNickname: string,
aGlobalTable: boolean,
aStrict: boolean,
aError: { value: string },
): boolean {
const table = aManager.Table(
aTableType,
aGlobalTable ? LIBRARY_TABLE_SCOPE.GLOBAL : LIBRARY_TABLE_SCOPE.PROJECT,
);
if (!table) {
if (aStrict) aError.value = 'Unable to access the library table.';
return !aStrict;
}
const fullPath = aLibraryPath;
if (table.HasRow(aNickname)) {
const row = table.Row(aNickname);
if (row && row.URI() !== fullPath) {
row.SetURI(fullPath);
if (!table.Save().ok) {
aError.value = 'Failed to update the library table.';
return false;
}
}
return true;
}
const row = table.InsertRow();
row.SetNickname(aNickname);
row.SetURI(fullPath);
row.SetType('KiCad');
row.SetOptions('');
row.SetDescription('Remote download');
row.SetOk(true);
if (!table.Save().ok) {
aError.value = 'Failed to save the library table.';
return false;
}
return true;
}
/**
* What `PlaceRemoteDownloadedSymbol` asks of the schematic editor:
* `GetLibSymbol`, and `PostAction( SCH_ACTIONS::placeSymbol, { symbol, true } )`
* with a new `SCH_SYMBOL` of it on the current sheet, autoplaced when the
* preference is on — the window builds and places the symbol.
*/
export interface REMOTE_SYMBOL_PLACEMENT_FRAME {
GetLibSymbol(aLibId: LIB_ID): Promise<LIB_SYMBOL | null>;
/** `aFrame->Raise()` then the placeSymbol action; false when there is no tool manager. */
PlaceSymbol(aLibSymbol: LIB_SYMBOL, aLibId: LIB_ID): boolean;
}
/** `PlaceRemoteDownloadedSymbol` (:210-248). */
export async function PlaceRemoteDownloadedSymbol(
aFrame: REMOTE_SYMBOL_PLACEMENT_FRAME | null,
aNickname: string,
aLibItemName: string,
aError: { value: string },
): Promise<boolean> {
if (!aFrame) {
aError.value = 'No schematic editor is available for placement.';
return false;
}
const libId = new LIB_ID();
libId.SetLibNickname(aNickname);
libId.SetLibItemName(aLibItemName);
const libSymbol = await aFrame.GetLibSymbol(libId);
if (!libSymbol) {
aError.value = 'Unable to load the downloaded symbol for placement.';
return false;
}
if (!aFrame.PlaceSymbol(libSymbol, libId)) {
aError.value = 'Unable to access the schematic placement tools.';
return false;
}
return true;
}
/**
* `LoadRemoteSymbolFromPayload` (:251-314): the payload written to a temp file, read back by
* the KiCad symbol plugin, and a copy of \a aLibItemName out of it.
*/
export function LoadRemoteSymbolFromPayload(
aPayload: Uint8Array,
aLibItemName: string,
aError: { value: string },
): LIB_SYMBOL | null {
if (aPayload.length === 0) {
aError.value = 'Symbol payload was empty.';
return null;
}
const tempPath = wxCreateTempFileName('remote_symbol');
if (tempPath === '') {
aError.value = 'Unable to create a temporary file for the symbol payload.';
return null;
}
if (!wxWriteFileSync(tempPath, aPayload)) {
aError.value = 'Unable to create a temporary file for the symbol payload.';
wxRemoveFile(tempPath);
return null;
}
const plugin = new SCH_IO_KICAD_SEXPR(); // SCH_IO_MGR::FindPlugin( SCH_KICAD )
let symbol: LIB_SYMBOL | null = null;
try {
const loaded = plugin.LoadSymbol(tempPath, aLibItemName);
if (loaded) symbol = LIB_SYMBOL.copyOf(loaded);
else aError.value = 'Symbol payload did not include the expected symbol.';
} catch (e) {
aError.value = `Unable to decode the symbol payload: ${e instanceof Error ? e.message : String(e)}`;
}
wxRemoveFile(tempPath);
return symbol;
}
/**
* `BuildRemoteLibId` (:317-330): `<prefix>_<library>` (sanitised, lower
* case, "footprints" when empty) and the sanitised item name ("footprint").
*/
export function BuildRemoteLibId(aResolvedLibrary: string, aResolvedItemName: string): LIB_ID {
const nickname = `${RemoteLibraryPrefix()}_${SanitizeRemoteFileComponent(aResolvedLibrary, 'footprints', true)}`;
const itemName = SanitizeRemoteFileComponent(aResolvedItemName, 'footprint');
const id = new LIB_ID();
id.SetLibNickname(nickname);
id.SetLibItemName(itemName);
return id;
}
/**
* `ApplyFootprintLinks` (:333-350): the first footprint becomes the symbol's
* Footprint field; each further one is added to its footprint filters by item
* name.
*/
export function ApplyFootprintLinks(aSymbol: LIB_SYMBOL, aLinks: readonly LIB_ID[]): void {
if (aLinks.length === 0) return;
aSymbol.SetFootprintProp(aLinks[0]!.GetUniStringLibId());
if (aLinks.length === 1) return;
const filters = aSymbol.GetFPFilters();
for (let i = 1; i < aLinks.length; ++i) filters.push(aLinks[i]!.GetUniStringLibItemName());
aSymbol.SetFPFilters(filters);
}