@markii/host 0.0.1 → 0.17.0-next.3

package/dist/packs/pack-paths.js

@@ -0,0 +1,105 @@
+/**
+ * Resolves a host's pack-folder setting entries to absolute folder paths.
+ * Pure (paths in, a base directory in, absolute paths out) so it is
+ * unit-testable without a real workspace/vault.
+ *
+ * `baseDir` is deliberately a generic name: what it MEANS differs per host
+ * (VS Code resolves a relative entry against the open workspace folder,
+ * since `markii.packs` is a user-scoped setting; an Obsidian plugin
+ * resolves it against the open vault, since its pack-folder list is a
+ * device-local setting that can be opened against several vaults) but the
+ * resolution RULE is identical, so only the base directory's identity is a
+ * host concern — reading the setting itself, and naming what "relative"
+ * means in a diagnostic message, stays in each host's own app code.
+ *
+ * DECISION: a relative entry is resolved against
+ * `baseDir` as given by the caller; an absolute entry is used as-is. This
+ * matches how a user reads the setting's own description: "this pack
+ * folder, relative to my project/vault".
+ */
+import { isAbsolutePath, joinPath } from '../path-util.js';
+/**
+ * Expands a leading `~` in `entry` against `homeDir` — `~` alone, or
+ * `~/...`/`~\...` (both separators accepted regardless of host platform, so
+ * a setting written on one OS still expands sensibly if synced to
+ * another). Any other entry (including one that merely CONTAINS a `~`
+ * elsewhere, or has no `homeDir` to expand against) passes through
+ * unchanged. This is convenience, not path resolution: the result still
+ * goes through the ordinary absolute/relative handling in
+ * `resolvePackPaths` below, exactly like a path the user typed out in
+ * full.
+ */
+function expandHome(entry, homeDir) {
+    if (homeDir === undefined)
+        return entry;
+    if (entry === '~')
+        return homeDir;
+    if (entry.startsWith('~/') || entry.startsWith('~\\')) {
+        return joinPath(homeDir, entry.slice(2));
+    }
+    return entry;
+}
+/**
+ * Resolves each entry in `packs` to an absolute path. `homeDir` is a plain
+ * parameter (not read via `os.homedir()` internally) so this stays testable
+ * against a fixed value instead of the real host's home directory; the real
+ * caller (each host's own `pack-context.ts`) passes `os.homedir()` itself.
+ * Omitted (or `undefined`) disables `~` expansion entirely — a `~` entry is
+ * then simply relative like any other.
+ *
+ * - A `~`/`~/...` entry is expanded against `homeDir` FIRST (`expandHome`)
+ *   — this makes an absolute path pleasant to write, which matters because
+ *   a relative entry can mean a different folder in every window/vault it
+ *   happens to be open in, so an absolute (or `~`-relative) entry is the
+ *   only spelling that means the same folder everywhere.
+ * - An entry that is (now) already absolute passes through UNCHANGED —
+ *   never re-rooted, and never rejected for pointing outside `baseDir`,
+ *   since an absolute path is the user explicitly naming a folder wherever
+ *   it is (docs/packs.md: packs are installed into the application, not
+ *   jailed the way a bundle's contents are).
+ * - A relative entry (still relative after `~` expansion) is joined
+ *   against `baseDir` and NORMALIZED (`path.normalize` via `path.join`,
+ *   which collapses `..` segments syntactically). A relative entry that
+ *   climbs out of `baseDir` via `..` is intentionally still honored, for
+ *   the same reason an absolute entry is: this setting is a user-authored
+ *   trust decision, not a content-derived path that needs jailing — unlike
+ *   a bundle's `scripts/`/`assets/` paths (`@markii/bundle`'s
+ *   `normalizeBundlePath`), which DO get jailed because they come from
+ *   potentially-hostile bundle content, not from the user directly editing
+ *   their own settings.
+ * - `baseDir === undefined` (no workspace/vault open) leaves every relative
+ *   entry UNRESOLVED (returned as-is, unjoined) rather than guessing a
+ *   base — a relative entry with nothing open cannot mean anything, so the
+ *   caller's later folder-read simply fails to find a `pack.json` there
+ *   and `discoverPacks` quietly skips it, the same cleanliness posture as
+ *   any other unreadable folder.
+ *
+ * Never throws — every input is a configuration string a user typed by
+ * hand, and a malformed one should degrade to "not found", not to a crash.
+ */
+export function resolvePackPaths(packs, baseDir, homeDir) {
+    return packs.map((entry) => {
+        const expanded = expandHome(entry, homeDir);
+        if (isAbsolutePath(expanded))
+            return expanded;
+        if (baseDir === undefined)
+            return expanded;
+        return joinPath(baseDir, expanded);
+    });
+}
+/**
+ * The detection half of the relative-entry diagnostics: the ORIGINAL
+ * (unexpanded) entries in
+ * `packs` that are relative once `~` expansion is accounted for — i.e.
+ * exactly the entries `resolvePackPaths` resolves against `baseDir` rather
+ * than using as-is. A relative entry can silently mean a different folder
+ * in every window/vault it happens to be open in, so a caller surfaces
+ * these to its own diagnostics surface, in its own wording (each host
+ * names its setting and the ambiguity differently — see this module's top
+ * doc comment); `resolvePackPaths` keeps resolving them exactly as it
+ * always has: this function only ever adds a warning, never changes
+ * behavior.
+ */
+export function relativePackEntries(packs, homeDir) {
+    return packs.filter((entry) => !isAbsolutePath(expandHome(entry, homeDir)));
+}

package/dist/packs/pack-render-registry.d.ts

@@ -0,0 +1,82 @@
+import type { PackManifest } from '@markii/pack';
+/**
+ * The renderer-specific half of building a pack-aware registry: the
+ * renderer's own `loadPack`, `createRegistry` and `mergeRegistries`. A
+ * React host passes `@markii/react`'s `reactPackEngine`; the host layer
+ * itself names no renderer.
+ */
+export interface PackRegistryEngine<TRegistry extends object = object, TEntry = unknown> {
+    loadPack(manifest: PackManifest, componentModules: Record<string, TEntry>): {
+        registry: TRegistry;
+        dropped?: {
+            name: string;
+            engine: string;
+        };
+    };
+    createRegistry(entries?: Record<string, TEntry>): TRegistry;
+    mergeRegistries(...registries: TRegistry[]): TRegistry;
+}
+/** One registration a compiled pack script queued by calling `window.__markiiRegisterPack(manifestJson, componentModules)` (see `./pack-build.ts`'s top doc comment for the full registration convention). Structurally identical across every host that satisfies the convention. */
+export interface QueuedPackRegistration {
+    readonly manifestJson: unknown;
+    readonly componentModules: unknown;
+}
+/**
+ * One composed directive name two DIFFERENT packs both claimed. Under
+ * `@markii/pack`'s current underscore join (issue #19) this cannot arise
+ * from two packs' names and local names composing to the same string — the
+ * join is bijective (see `namespace.ts`'s `composeDirectiveName` doc
+ * comment) — so this is a defense-in-depth invariant, not a reachable case
+ * of ordinary pack composition. It stays because a hand-written pack
+ * registration script (or a future regression in the composition rule)
+ * could still hand `buildRenderRegistry` two registrations that carry the
+ * identical composed name; when that happens the FIRST claimant keeps the
+ * name and the later one is dropped, exactly like a malformed registration.
+ */
+export interface DuplicateComposedName {
+    readonly composedName: string;
+    /** The pack whose component kept the name. */
+    readonly keptPack: string;
+    /** The pack whose component was skipped because the name was already taken. */
+    readonly skippedPack: string;
+}
+/** What `buildRenderRegistry` reports alongside the merged registry — developer-facing diagnostics for a caller to fold into its own surface, never shown as page content. */
+export interface BuildRenderRegistryResult<TRegistry extends object = object> {
+    readonly registry: TRegistry;
+    /** One line per malformed registration, dropped rather than installed. */
+    readonly invalidReasons: readonly string[];
+    /** Non-empty only when two or more validated registrations shared a namespace — the WHOLE install was then rejected (docs/packs.md's install-time rejection rule) and `registry` falls back to `defaultRegistry` alone. */
+    readonly collisions: readonly string[];
+    /** One entry per composed directive name claimed by two different packs — see `DuplicateComposedName`. Always empty for registrations that went through ordinary composition; kept as an executable invariant, not dead code (see `./pack-render-registry.test.ts`'s constructed-collision test). */
+    readonly duplicateComposedNames: readonly DuplicateComposedName[];
+    /**
+     * One entry per validated, non-colliding pack whose manifest declares an
+     * engine `@markii/react`'s `loadPack` cannot run. Before
+     * this field existed, such a pack installed as an empty contribution
+     * with no record anywhere that it had even been attempted — every
+     * directive under its namespace fell through to the ordinary
+     * unknown-component fallback, indistinguishable from a directive that
+     * was never a pack component at all. Always empty for an ordinary
+     * all-react-engine install.
+     */
+    readonly droppedEngines: readonly {
+        name: string;
+        engine: string;
+    }[];
+}
+/**
+ * Builds the render registry: `defaultRegistry` merged with every
+ * successfully validated, non-colliding pack registration in `queued`.
+ * Never throws:
+ *
+ * - an individual malformed registration is dropped (reason recorded, never
+ *   shown on the page);
+ * - a namespace collision between two loaded packs (the same pack name
+ *   registered twice) rejects the WHOLE install (matching docs/packs.md's
+ *   install-time rejection rule) and this function falls back to
+ *   `defaultRegistry` alone;
+ * - a composed-directive-name collision between two DIFFERENTLY named packs
+ *   (see `DuplicateComposedName`) drops only the later claimant's
+ *   component, not the whole pack.
+ */
+export declare function buildRenderRegistry<TRegistry extends object, TEntry>(queued: readonly QueuedPackRegistration[], defaultRegistry: TRegistry, engine: PackRegistryEngine<TRegistry, TEntry>): BuildRenderRegistryResult<TRegistry>;

package/dist/packs/pack-render-registry.js

@@ -0,0 +1,182 @@
+/**
+ * Validates a batch of `QueuedPackRegistration`s and merges them into a
+ * render `Registry` on top of a base registry, using `@markii/react`'s
+ * `loadPack` per pack (namespace-collision rejection reimplemented here so
+ * this module can also guard against a same-composed-name collision
+ * between two differently named packs — see `DuplicateComposedName` and
+ * `mergePacksKeepingFirstClaim`).
+ *
+ * Every entry here crossed a boundary from a SEPARATELY EVALUATED script (a
+ * pack's compiled artifact, not code a host's own bundle compiled) — same
+ * trust as that bundle once loaded (docs/security.md: "packs are
+ * user-installed/trusted"), but still validated structurally before use,
+ * because "trusted" does not mean "guaranteed well-formed": a buggy or
+ * half-built pack script must degrade the SAME way an unsupported engine or
+ * a missing component module already does in `@markii/react`'s `loadPack`
+ * (an empty contribution, never a crash), not bring down the rest of a
+ * preview.
+ *
+ * Host-neutral by design: this module takes an already-collected array of
+ * queued registrations as a plain parameter, and returns the outcome as
+ * data (never logs or throws), so a host wires up wherever those
+ * registrations came from — VS Code reads `window.__markiiPackRegistrations`
+ * off its webview and logs the result to its output channel; an Obsidian
+ * plugin evaluates each pack's compiled script in-process
+ * (`collectPackRegistrations`) and folds the result into its own
+ * diagnostics. Reading a host-specific global and deciding where to log a
+ * diagnostic line both stay in that host's own app code.
+ */
+import { detectNamespaceCollisions, parsePackManifest } from '@markii/pack';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+/** Structurally validates one `componentModules` object: every OWN entry has a function `component` and an optional boolean `inline`. Read with `Object.hasOwn` only — the same hostile-map discipline `@markii/pack`/`@markii/react` use throughout, so a `componentModules` object with a poisoned `__proto__` can't leak an inherited value in as a registered component. */
+function isPackComponentModules(value) {
+    if (!isPlainObject(value))
+        return false;
+    for (const key of Object.keys(value)) {
+        if (!hasOwn(value, key))
+            continue;
+        const entry = value[key];
+        if (!isPlainObject(entry))
+            return false;
+        if (typeof entry.component !== 'function')
+            return false;
+        if (hasOwn(entry, 'inline') && typeof entry.inline !== 'boolean') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * One queued entry, validated into a `PackToInstall`, or `undefined` if
+ * either half fails validation — the reason is returned rather than logged
+ * directly, so the caller can fold it into its own diagnostics the same way
+ * every other pack failure is reported.
+ *
+ * Deliberately NOT exported, including from `../browser.ts`: every caller,
+ * VS Code's webview included, reaches this through `buildRenderRegistry`,
+ * which runs it per queued entry. A host reads its own registration queue
+ * off its own global and hands over the batch; validating that batch is
+ * this module's job, and keeping the per-entry step private means there is
+ * one entry point into it rather than two.
+ */
+function toPackToInstall(entry, index) {
+    if (typeof entry.manifestJson !== 'string') {
+        return {
+            invalidReason: `pack registration #${String(index)} did not provide a manifest JSON string; ignored.`,
+        };
+    }
+    const parsed = parsePackManifest(entry.manifestJson);
+    if (!parsed.ok) {
+        return {
+            invalidReason: `pack registration #${String(index)}'s manifest is invalid (${parsed.errors.join('; ')}); ignored.`,
+        };
+    }
+    if (!isPackComponentModules(entry.componentModules)) {
+        return {
+            invalidReason: `pack "${parsed.manifest.name}"'s registered components are malformed; ignored.`,
+        };
+    }
+    const manifest = parsed.manifest;
+    return { pack: { manifest, componentModules: entry.componentModules } };
+}
+/**
+ * Loads every pack's own registry (`@markii/react`'s `loadPack`, which
+ * already gates on engine and skips an unsatisfied component) and merges
+ * them onto `base` left to right, but — unlike `@markii/react`'s ordinary
+ * `mergeRegistries` last-wins semantics — keeps the FIRST pack to claim a
+ * given composed directive name and skips any later pack that claims the
+ * same name, recording the skip as a `DuplicateComposedName`. `base`'s own
+ * entries are not part of this check: a pack's composed name overriding an
+ * unrelated `base` entry is ordinary last-wins behavior, the same as
+ * `installPacks` already gives it.
+ */
+function mergePacksKeepingFirstClaim(packs, base, engine) {
+    const merged = { ...base };
+    const owner = new Map();
+    const duplicateComposedNames = [];
+    const droppedEngines = [];
+    for (const pack of packs) {
+        const { registry: loaded, dropped } = engine.loadPack(pack.manifest, pack.componentModules);
+        if (dropped)
+            droppedEngines.push(dropped);
+        for (const composedName of Object.keys(loaded)) {
+            if (!Object.hasOwn(loaded, composedName))
+                continue;
+            const existingOwner = owner.get(composedName);
+            if (existingOwner !== undefined) {
+                duplicateComposedNames.push({
+                    composedName,
+                    keptPack: existingOwner,
+                    skippedPack: pack.manifest.name,
+                });
+                continue;
+            }
+            owner.set(composedName, pack.manifest.name);
+            merged[composedName] = loaded[composedName];
+        }
+    }
+    return {
+        registry: engine.createRegistry(merged),
+        duplicateComposedNames,
+        droppedEngines,
+    };
+}
+/**
+ * Builds the render registry: `defaultRegistry` merged with every
+ * successfully validated, non-colliding pack registration in `queued`.
+ * Never throws:
+ *
+ * - an individual malformed registration is dropped (reason recorded, never
+ *   shown on the page);
+ * - a namespace collision between two loaded packs (the same pack name
+ *   registered twice) rejects the WHOLE install (matching docs/packs.md's
+ *   install-time rejection rule) and this function falls back to
+ *   `defaultRegistry` alone;
+ * - a composed-directive-name collision between two DIFFERENTLY named packs
+ *   (see `DuplicateComposedName`) drops only the later claimant's
+ *   component, not the whole pack.
+ */
+export function buildRenderRegistry(queued, defaultRegistry, engine) {
+    const packs = [];
+    const invalidReasons = [];
+    queued.forEach((entry, index) => {
+        const { pack, invalidReason } = toPackToInstall(entry, index);
+        if (pack)
+            packs.push(pack);
+        if (invalidReason)
+            invalidReasons.push(invalidReason);
+    });
+    if (packs.length === 0) {
+        return {
+            registry: defaultRegistry,
+            invalidReasons,
+            collisions: [],
+            duplicateComposedNames: [],
+            droppedEngines: [],
+        };
+    }
+    const namespaces = packs.map((pack) => pack.manifest.name);
+    const namespaceCollisions = detectNamespaceCollisions(namespaces);
+    if (namespaceCollisions.length > 0) {
+        return {
+            registry: engine.mergeRegistries(engine.createRegistry(), defaultRegistry),
+            invalidReasons,
+            collisions: namespaceCollisions.map((collision) => collision.namespace),
+            duplicateComposedNames: [],
+            droppedEngines: [],
+        };
+    }
+    const { registry, duplicateComposedNames, droppedEngines } = mergePacksKeepingFirstClaim(packs, defaultRegistry, engine);
+    return {
+        registry,
+        invalidReasons,
+        collisions: [],
+        duplicateComposedNames,
+        droppedEngines,
+    };
+}

package/dist/packs/pack-scripts.d.ts

@@ -0,0 +1,20 @@
+import type { DiscoveredPack } from './discover.js';
+import type { PackModulesMap } from '../run/lua-resolver.js';
+export interface PackScriptsReader {
+    /** Lists one directory's immediate entries, or `[]` if it does not exist / cannot be read (never throws — a pack with no `scripts/` folder is the ordinary case). */
+    readDirectory(absoluteDir: string): Promise<ReadonlyArray<{
+        name: string;
+        isDirectory: boolean;
+    }>>;
+    /** Reads one file's UTF-8 text, or `undefined` if it cannot be read. */
+    readFile(absolutePath: string): Promise<string | undefined>;
+}
+/**
+ * Builds the full `PackModulesMap` for `packs`: every discovered pack's
+ * namespace mapped to its `scripts/*.lua` files, keyed by their
+ * jail-normalized relative path. A pack with no `scripts/` directory (or an
+ * unreadable one) simply contributes an empty module map — a
+ * `require "thatPack/anything"` then resolves as an ordinary "no such
+ * module", never a crash.
+ */
+export declare function loadPackModules(packs: readonly DiscoveredPack[], reader: PackScriptsReader): Promise<PackModulesMap>;

package/dist/packs/pack-scripts.js

@@ -0,0 +1,96 @@
+/**
+ * Host-side, UI-free loader that reads every pack's `scripts/*.lua` files
+ * ahead of a run, producing the `PackModulesMap` `./run/lua-resolver.ts`'s
+ * `createPackModuleResolver` looks up synchronously inside the Run worker —
+ * see that module's doc comment for why the reading happens here, on the
+ * host, rather than inside the worker.
+ *
+ * Filesystem access is injected (`PackScriptsReader`) so this module is
+ * testable with an in-memory fake; `createNodeReader` in `../node-fs.ts`
+ * (exported from `@markii/host/node`) is the real `node:fs/promises`-backed
+ * implementation a Node host's pack-loading composition wires up.
+ */
+import { joinPath } from '../path-util.js';
+import { normalizeBundlePath } from '@markii/bundle';
+/** A sane upper bound on how many `.lua` files one pack's `scripts/` tree may contribute — defense in depth against a pathological pack folder (a symlink cycle a directory walk would otherwise never terminate on, or simply an absurd number of files) turning "load the installed packs" into an unbounded scan. */
+const MAX_SCRIPT_FILES_PER_PACK = 500;
+/** Recursion depth cap for the same reason — a plain bound alongside the file-count cap, independent of it. */
+const MAX_SCRIPT_DIR_DEPTH = 16;
+/**
+ * A per-file size cap on a pack's `scripts/*.lua` (H-2, pass-3 pentest report
+ * section 10.2). Packs are user-installed, trusted folders, so this is
+ * defense in depth rather than a trust boundary — but it matches the posture
+ * `buildBundleSnapshot` already takes for bundle files: a single file's whole
+ * text is read into the host process and then structured-cloned into the
+ * Run worker's job, so an absurdly large `.lua` (accidental or hostile) would
+ * otherwise pull an unbounded amount into host memory. A file over this cap
+ * is skipped exactly like an unreadable one — `require`-ing it then resolves
+ * as an ordinary "no such module", never a crash. 1 MB is far above any real
+ * shared Lua module while still bounding a pathological one.
+ */
+const MAX_SCRIPT_FILE_BYTES = 1_000_000;
+/**
+ * Walks `pack.scriptsDir` (relative to it) collecting every `.lua` file's
+ * bundle-jail-normalized relative path -> source text. A relative path the
+ * jail rejects (should not arise from a real directory listing, but this is
+ * defense in depth, matching every other filesystem-adjacent module in this
+ * codebase) is silently skipped rather than throwing — same cleanliness
+ * posture as `./discover.ts`. An unreadable individual file is skipped the
+ * same way.
+ */
+async function collectPackModules(pack, reader) {
+    const result = Object.create(null);
+    let fileCount = 0;
+    async function walk(relativeDir, depth) {
+        if (depth > MAX_SCRIPT_DIR_DEPTH)
+            return;
+        const absoluteDir = relativeDir
+            ? joinPath(pack.scriptsDir, relativeDir)
+            : pack.scriptsDir;
+        const entries = await reader.readDirectory(absoluteDir);
+        for (const entry of entries) {
+            if (fileCount >= MAX_SCRIPT_FILES_PER_PACK)
+                return;
+            const relativePath = relativeDir
+                ? `${relativeDir}/${entry.name}`
+                : entry.name;
+            if (entry.isDirectory) {
+                await walk(relativePath, depth + 1);
+                continue;
+            }
+            if (!entry.name.endsWith('.lua'))
+                continue;
+            const normalized = normalizeBundlePath(relativePath);
+            if (!normalized.ok)
+                continue;
+            const absolutePath = joinPath(pack.scriptsDir, relativePath);
+            const source = await reader.readFile(absolutePath);
+            if (source === undefined)
+                continue;
+            // H-2: skip a file whose UTF-8 size exceeds the per-file cap, same as an
+            // unreadable one. `TextEncoder` measures the encoded bytes (what
+            // actually crosses into the worker), not the JS string's UTF-16 length.
+            if (new TextEncoder().encode(source).length > MAX_SCRIPT_FILE_BYTES)
+                continue;
+            result[normalized.path] = source;
+            fileCount += 1;
+        }
+    }
+    await walk('', 0);
+    return result;
+}
+/**
+ * Builds the full `PackModulesMap` for `packs`: every discovered pack's
+ * namespace mapped to its `scripts/*.lua` files, keyed by their
+ * jail-normalized relative path. A pack with no `scripts/` directory (or an
+ * unreadable one) simply contributes an empty module map — a
+ * `require "thatPack/anything"` then resolves as an ordinary "no such
+ * module", never a crash.
+ */
+export async function loadPackModules(packs, reader) {
+    const map = Object.create(null);
+    for (const pack of packs) {
+        map[pack.manifest.name] = await collectPackModules(pack, reader);
+    }
+    return map;
+}

package/dist/packs/pack-trust.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The DEVICE-LOCAL pack trust list: which installed-pack namespaces this
+ * device authorizes to load (docs/packs.md). Every namespace named here
+ * has its pack code evaluated at host trust, so the list authorizes code
+ * execution and must live in device-local state (the adapter's
+ * `memento`), never in anything that travels with a vault, a workspace
+ * file, or a sync service.
+ *
+ * A pack folder can sit in the install root without being trusted: it
+ * arrived through a file sync, or a user copied it there by hand. Such a
+ * folder is never loaded until its namespace is added here, exactly like
+ * a freshly installed one, and the consent prompt is asked either way.
+ * The trust list, not the presence of a folder, decides whether code
+ * runs. `../host/pack-trust-behavior.ts` enforces that for every host
+ * that declares `trust: 'device-list'`.
+ *
+ * Pure and environment-free, so the shape and its hostile-input
+ * normalization are unit-testable with no host in sight.
+ */
+/** The memento key this shape lives under. It is the key Obsidian has always stored this list under, so an existing device keeps its trust list. */
+export declare const PACK_TRUST_STORAGE_KEY = "markii:installedPacks";
+/** A sane upper bound on how many namespaces this list may hold : a real device installs a handful of packs; this only exists to bound a hostile or corrupt stored value. */
+export declare const MAX_TRUSTED_PACKS = 200;
+/** One namespace this device trusts, and the version it was installed at (the manifest's own `version` field, or `undefined` when the pack declares none). */
+export interface PackTrustEntry {
+    readonly namespace: string;
+    readonly version?: string;
+}
+export interface PackTrustList {
+    readonly entries: readonly PackTrustEntry[];
+}
+export declare const DEFAULT_PACK_TRUST_LIST: PackTrustList;
+/**
+ * Normalizes whatever `app.loadLocalStorage(PACK_TRUST_STORAGE_KEY)` handed
+ * back into a well-formed `PackTrustList` : hostile-shape-guarded the same
+ * way every other device-local shape in this plugin is, since this is also
+ * hand-editable, foreign-version-shaped data in principle. A malformed
+ * entry is dropped rather than failing the whole read; duplicates are
+ * removed by namespace, first occurrence wins; the list is bounded by
+ * `MAX_TRUSTED_PACKS`.
+ */
+export declare function normalizePackTrustList(data: unknown): PackTrustList;
+/** Whether `namespace` is trusted on this device. */
+export declare function isPackTrusted(list: PackTrustList, namespace: string): boolean;
+/**
+ * Adds (or replaces) `namespace`'s trust entry, recording `version` when
+ * given. Used both by a fresh install and by "Enable" for a pack folder
+ * that was already present on disk. Returns the same list unchanged (never
+ * a new object) when the entry is already present with the same version,
+ * so a caller can skip a write that would change nothing.
+ */
+export declare function trustPack(list: PackTrustList, namespace: string, version?: string): PackTrustList;
+/**
+ * Removes `namespace`'s trust entry. Returns the same list unchanged when
+ * it was not present, so a caller can skip a no-op write.
+ */
+export declare function untrustPack(list: PackTrustList, namespace: string): PackTrustList;

package/dist/packs/pack-trust.js

@@ -0,0 +1,111 @@
+/**
+ * The DEVICE-LOCAL pack trust list: which installed-pack namespaces this
+ * device authorizes to load (docs/packs.md). Every namespace named here
+ * has its pack code evaluated at host trust, so the list authorizes code
+ * execution and must live in device-local state (the adapter's
+ * `memento`), never in anything that travels with a vault, a workspace
+ * file, or a sync service.
+ *
+ * A pack folder can sit in the install root without being trusted: it
+ * arrived through a file sync, or a user copied it there by hand. Such a
+ * folder is never loaded until its namespace is added here, exactly like
+ * a freshly installed one, and the consent prompt is asked either way.
+ * The trust list, not the presence of a folder, decides whether code
+ * runs. `../host/pack-trust-behavior.ts` enforces that for every host
+ * that declares `trust: 'device-list'`.
+ *
+ * Pure and environment-free, so the shape and its hostile-input
+ * normalization are unit-testable with no host in sight.
+ */
+/** The memento key this shape lives under. It is the key Obsidian has always stored this list under, so an existing device keeps its trust list. */
+export const PACK_TRUST_STORAGE_KEY = 'markii:installedPacks';
+/** A sane upper bound on how many namespaces this list may hold : a real device installs a handful of packs; this only exists to bound a hostile or corrupt stored value. */
+export const MAX_TRUSTED_PACKS = 200;
+export const DEFAULT_PACK_TRUST_LIST = { entries: [] };
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Normalizes one raw entry, or `undefined` when it does not have a usable `namespace`. A non-string, empty, or whitespace-only `namespace` is dropped rather than crashing the whole read; a non-string `version` is dropped (the entry survives, just without one). */
+function normalizeEntry(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const namespace = raw.namespace;
+    if (typeof namespace !== 'string')
+        return undefined;
+    const trimmed = namespace.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const version = raw.version;
+    return typeof version === 'string' && version.trim().length > 0
+        ? { namespace: trimmed, version: version.trim() }
+        : { namespace: trimmed };
+}
+/**
+ * Normalizes whatever `app.loadLocalStorage(PACK_TRUST_STORAGE_KEY)` handed
+ * back into a well-formed `PackTrustList` : hostile-shape-guarded the same
+ * way every other device-local shape in this plugin is, since this is also
+ * hand-editable, foreign-version-shaped data in principle. A malformed
+ * entry is dropped rather than failing the whole read; duplicates are
+ * removed by namespace, first occurrence wins; the list is bounded by
+ * `MAX_TRUSTED_PACKS`.
+ */
+export function normalizePackTrustList(data) {
+    if (!isPlainObject(data))
+        return { ...DEFAULT_PACK_TRUST_LIST };
+    const rawEntries = data.entries;
+    if (!Array.isArray(rawEntries))
+        return { ...DEFAULT_PACK_TRUST_LIST };
+    const seen = new Set();
+    const entries = [];
+    for (const rawEntry of rawEntries) {
+        if (entries.length >= MAX_TRUSTED_PACKS)
+            break;
+        const entry = normalizeEntry(rawEntry);
+        if (!entry)
+            continue;
+        if (seen.has(entry.namespace))
+            continue;
+        seen.add(entry.namespace);
+        entries.push(entry);
+    }
+    return { entries };
+}
+/** Whether `namespace` is trusted on this device. */
+export function isPackTrusted(list, namespace) {
+    return list.entries.some((entry) => entry.namespace === namespace);
+}
+/**
+ * Adds (or replaces) `namespace`'s trust entry, recording `version` when
+ * given. Used both by a fresh install and by "Enable" for a pack folder
+ * that was already present on disk. Returns the same list unchanged (never
+ * a new object) when the entry is already present with the same version,
+ * so a caller can skip a write that would change nothing.
+ */
+export function trustPack(list, namespace, version) {
+    const trimmed = namespace.trim();
+    if (trimmed.length === 0)
+        return list;
+    const existing = list.entries.find((entry) => entry.namespace === trimmed);
+    if (existing && existing.version === version)
+        return list;
+    const withoutExisting = list.entries.filter((entry) => entry.namespace !== trimmed);
+    const next = [
+        ...withoutExisting,
+        version !== undefined
+            ? { namespace: trimmed, version }
+            : { namespace: trimmed },
+    ];
+    return { entries: next.slice(0, MAX_TRUSTED_PACKS) };
+}
+/**
+ * Removes `namespace`'s trust entry. Returns the same list unchanged when
+ * it was not present, so a caller can skip a no-op write.
+ */
+export function untrustPack(list, namespace) {
+    if (!list.entries.some((entry) => entry.namespace === namespace)) {
+        return list;
+    }
+    return {
+        entries: list.entries.filter((entry) => entry.namespace !== namespace),
+    };
+}