@markii/host 0.0.1 → 0.17.0-next.2

package/dist/host/pack-install.js

@@ -0,0 +1,189 @@
+/**
+ * The `.mkp` pack-install decision logic, merged from
+ * `apps/vscode/src/packs/install-pack.ts` and
+ * `apps/obsidian/src/packs/install-pack.ts` (survey finding A2: the single
+ * biggest duplication finding in the survey — identical function names,
+ * identical types, near-identical wording, differing only in that
+ * Obsidian refuses a bundled-namespace archive before the consent prompt
+ * and VS Code has no such concept).
+ *
+ * `reservedNamespaces` generalizes Obsidian's `bundledNamespaces`: it
+ * defaults to empty, so VS Code's behavior is byte-identical to before
+ * (the `'reserved'` outcome branch simply never fires there), and
+ * Obsidian's adapter passes its three bundled namespaces
+ * (`read`/`dash`/`prep`) through `HostPackSource.reservedNamespaces()`.
+ *
+ * ORDER IS SECURITY-RELEVANT and preserved exactly: validate the archive,
+ * refuse a reserved namespace, ask consent to run the pack's code, ask
+ * before replacing an already-installed pack of the same namespace, and
+ * only then write anything to disk. Nothing is written until every
+ * applicable step has already said yes.
+ */
+import { joinPath } from '../path-util.js';
+import { openPackArchive } from '@markii/pack';
+import { describeArchiveError, writeArchiveContents } from './pack-archive.js';
+import { trustInstalledPack } from './pack-trust-behavior.js';
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Never throws: a validation failure, a declined prompt, or a write
+ * failure all come back as a structured outcome. Order: validate the
+ * archive first (a rejected archive is never even offered the consent
+ * prompt), then refuse a reserved namespace, then ask consent to run its
+ * code, then, only if a pack of the same namespace is already installed,
+ * ask to replace it. Nothing is written until every applicable step has
+ * said yes.
+ *
+ * Every prompt routes through `adapter.prompt` with `kind:
+ * 'pack-install-consent'`/`'pack-replace'`, per `HostAdapter`'s contract —
+ * a host that can only show a non-blocking surface must deny rather than
+ * assume yes.
+ */
+export async function installPackFromArchive(adapter, options) {
+    const { archiveBytes, archivePath, installRoot, exists, extractFs, reservedNamespaces, } = options;
+    const opened = await openPackArchive(archiveBytes);
+    if (!opened.ok) {
+        return {
+            kind: 'rejected',
+            reason: `"${archivePath}" is not a valid pack archive: ${describeArchiveError(opened.error)}`,
+        };
+    }
+    const packName = opened.archive.manifest.name;
+    if (reservedNamespaces.has(packName)) {
+        return { kind: 'reserved', packName };
+    }
+    let consented;
+    try {
+        consented = await adapter.prompt({
+            kind: 'pack-install-consent',
+            message: installConsentMessage(packName, adapter.labels),
+            allowLabel: 'Install',
+            denyLabel: 'Cancel',
+            consequential: true,
+        });
+    }
+    catch (err) {
+        return { kind: 'rejected', reason: describeThrown(err) };
+    }
+    if (!consented) {
+        return { kind: 'declined', step: 'consent', packName };
+    }
+    const targetDir = joinPath(installRoot, packName);
+    let alreadyInstalled;
+    try {
+        alreadyInstalled = await exists(targetDir);
+    }
+    catch (err) {
+        return { kind: 'rejected', reason: describeThrown(err) };
+    }
+    let replaced = false;
+    if (alreadyInstalled) {
+        let proceed;
+        try {
+            proceed = await adapter.prompt({
+                kind: 'pack-replace',
+                message: installReplaceConfirmMessage(packName),
+                allowLabel: 'Replace',
+                denyLabel: 'Cancel',
+                consequential: true,
+            });
+        }
+        catch (err) {
+            return { kind: 'rejected', reason: describeThrown(err) };
+        }
+        if (!proceed) {
+            return { kind: 'declined', step: 'replace', packName };
+        }
+        replaced = true;
+    }
+    try {
+        await extractFs.removeDirectory(targetDir);
+        await writeArchiveContents(opened.archive, targetDir, extractFs);
+    }
+    catch (err) {
+        return {
+            kind: 'rejected',
+            reason: `could not install pack "${packName}": ${describeThrown(err)}`,
+        };
+    }
+    await trustInstalledPack(adapter, packName, targetDir);
+    return { kind: 'installed', packName, installedDir: targetDir, replaced };
+}
+/**
+ * The consent prompt's wording (AGENTS.md's product principles: "clean is
+ * not silent," and a consent step must say plainly what it authorizes).
+ * States outright that the pack's code will run inside the preview, since
+ * this is the one place that consent is asked, so it has to say it, not
+ * hint at it.
+ *
+ * CANONICAL WORDING CHOSEN over the two apps' prior copy (report this as a
+ * before/after pair): "from someone you trust" (Obsidian's phrasing) over
+ * "from a source you trust" (VS Code's), and `labels.previewNoun` ("the
+ * Markii preview" for both hosts) in place of VS Code's prior "every
+ * Markii preview" — `HostLabels.previewNoun` already gives both hosts the
+ * same noun, so the interpolation settles the wording rather than
+ * widening `HostLabels` for a distinction the record does not carry.
+ */
+export function installConsentMessage(packName, labels) {
+    return `Installing "${packName}" lets its code run inside ${labels.previewNoun}. Only install a pack from someone you trust.`;
+}
+/**
+ * The collision confirmation's wording: a namespace already installed,
+ * asked before replacing it. CANONICAL WORDING: "removes" (VS Code's prior
+ * wording) over Obsidian's prior "deletes" — see `tmp/W11-phase1b.md`'s
+ * before/after table for the exact strings this replaces.
+ */
+export function installReplaceConfirmMessage(packName) {
+    return `A pack named "${packName}" is already installed. Replacing it removes the installed copy and cannot be undone.`;
+}
+/**
+ * The one result message for the install command, matching this host's
+ * wording rules (two short sentences, no em dashes or parentheses in the
+ * popup; the full detail goes to the diagnostics surface).
+ *
+ * `reloadsAutomatically` is a per-host BEHAVIOR fact, not a wording noun:
+ * Obsidian's install command reloads every open view's packs immediately
+ * after a successful install, so its message says so; VS Code's install
+ * command does not (an installed pack still needs to be added to
+ * `markii.packs` before anything loads it), so it doesn't. Defaults to
+ * `false`.
+ */
+export function installPackMessage(outcome, archivePath, labels, reloadsAutomatically = false) {
+    if (outcome.kind === 'rejected') {
+        return `Markii: could not install a pack from "${archivePath}". Open ${labels.diagnosticsSurface} for details.`;
+    }
+    if (outcome.kind === 'reserved') {
+        return `Markii: "${outcome.packName}" is built in and cannot be installed. Nothing was installed.`;
+    }
+    if (outcome.kind === 'declined') {
+        return outcome.step === 'consent'
+            ? `Markii: install of "${outcome.packName}" cancelled. Nothing was installed.`
+            : `Markii: install of "${outcome.packName}" cancelled. The existing pack was kept.`;
+    }
+    const reloadSuffix = reloadsAutomatically ? ' Markii packs reloaded.' : '';
+    return outcome.replaced
+        ? `Markii: reinstalled pack "${outcome.packName}".${reloadSuffix}`
+        : `Markii: installed pack "${outcome.packName}".${reloadSuffix}`;
+}
+/** The full diagnostics-surface detail for one install attempt (AGENTS.md's "clean is not silent": the other of a failure's two homes). */
+export function installPackDiagnosticLines(outcome, archivePath) {
+    if (outcome.kind === 'rejected') {
+        return [
+            `Install pack from file rejected "${archivePath}": ${outcome.reason}`,
+        ];
+    }
+    if (outcome.kind === 'reserved') {
+        return [
+            `Install pack from file refused "${archivePath}": pack "${outcome.packName}" is a reserved namespace and cannot be installed.`,
+        ];
+    }
+    if (outcome.kind === 'declined') {
+        return [
+            `Install pack from file cancelled for "${archivePath}" (pack "${outcome.packName}") at the ${outcome.step} step; nothing was installed.`,
+        ];
+    }
+    return [
+        `Install pack from file installed pack "${outcome.packName}" from "${archivePath}" to ${outcome.installedDir}${outcome.replaced ? ' (replacing the previous install)' : ''}.`,
+    ];
+}

package/dist/host/pack-load.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The shared discovery path behind `loadPacks`, merged from
+ * `apps/vscode/src/packs/discover-configured-packs.ts` and
+ * `apps/obsidian/src/packs/discover-configured-packs.ts` (survey finding
+ * A3) plus the discovery-and-namespace-collection half both apps'
+ * `packs/pack-context.ts` also duplicate on top of it.
+ *
+ * Pack POLICY — which folders are even candidates before any content is
+ * read — is irreducibly host-specific (VS Code's resolved `markii.packs`
+ * setting merged with its bundled packs; Obsidian's trust-filtered
+ * installed folders merged with ITS bundled packs) and stays entirely
+ * app-side, behind `HostPackSource.authorizedFolders()`. Everything AFTER
+ * that list exists — read each folder's `pack.json`, validate it, drop a
+ * namespace collision, engine-gate against this renderer — was already the
+ * identical one-line call to `../packs/discover.ts`'s `discoverPacks` in
+ * both apps, and that is what this module is.
+ *
+ * This is the CHEAP catalog path (a pack's manifest only: names,
+ * namespaces, component attributes), the same shape both apps' Insert
+ * Component command and directive completion already used —
+ * deliberately not the heavier `pack-context.ts` composition (which also
+ * loads Lua modules and resolves or evaluates a webview registration
+ * script), since neither of those is anything `loadPacks`'s cheap-catalog
+ * callers need.
+ */
+import type { UnavailableComponent } from '@markii/stdlib';
+import type { DiscoveredPack, PackDirectoryLister, PackFileReader, SkippedPackFolder } from '../packs/discover.js';
+import type { HostAdapter, HostPackSource } from './adapter.js';
+/** The two file-system reads pack discovery needs, injected so this module has no Node dependency. */
+export interface PackDiscoveryIo {
+    readonly readFile: PackFileReader;
+    readonly listDirectory: PackDirectoryLister;
+}
+/**
+ * Discovery reads derived from the adapter's own `readFile` and
+ * `listFolder`. Both are held to discovery's never-rejects contract: an
+ * unreadable file is `undefined`, an unreadable folder is `[]`.
+ */
+export declare function packDiscoveryIoFromAdapter(adapter: Pick<HostAdapter, 'readFile' | 'listFolder'>): PackDiscoveryIo;
+export interface LoadPacksResult {
+    readonly packs: readonly DiscoveredPack[];
+    readonly skipped: readonly SkippedPackFolder[];
+    readonly namespaces: readonly string[];
+    /**
+     * Every component of every installed pack, including a pack dropped whole
+     * because it has nothing for this engine, with the engines each one has a
+     * view for. A host passes it to an engine that draws NO pack views, such
+     * as the static HTML export.
+     */
+    readonly components: readonly UnavailableComponent[];
+    /**
+     * The subset of `components` with no view for this host's engine: the list
+     * a host passes to its renderer's `unavailableComponents` option, so a
+     * note using one says "no view here" instead of "unknown component".
+     */
+    readonly unavailable: readonly UnavailableComponent[];
+}
+/**
+ * Discovers every pack under `folders`, engine-gated against
+ * `engine` (the host's renderer engine id, given by the caller) — the same
+ * posture a renderer's pack loader takes for an unsupported `engine`, so
+ * neither Insert Component nor completion ever offers a component this
+ * renderer could not render.
+ */
+export declare function discoverConfiguredPacks(folders: readonly string[], io: PackDiscoveryIo, engine: string): Promise<LoadPacksResult>;
+/**
+ * Runs `discoverConfiguredPacks` over `source.authorizedFolders()`. The
+ * caller (`createMarkiiHost`'s `loadPacks`) checks that
+ * `adapter.packs` exists before calling this — a host with no `packs`
+ * capability at all returns `Unsupported` first and never reaches here.
+ */
+export declare function loadPacksViaAdapter(source: HostPackSource, io: PackDiscoveryIo): Promise<LoadPacksResult>;

package/dist/host/pack-load.js

@@ -0,0 +1,57 @@
+import { componentsWithoutEngineView, declaredPackComponents, discoverPacks, installedNamespaces, } from '../packs/discover.js';
+/**
+ * Discovery reads derived from the adapter's own `readFile` and
+ * `listFolder`. Both are held to discovery's never-rejects contract: an
+ * unreadable file is `undefined`, an unreadable folder is `[]`.
+ */
+export function packDiscoveryIoFromAdapter(adapter) {
+    return {
+        readFile: async (absolutePath) => {
+            try {
+                return new TextDecoder().decode(await adapter.readFile(absolutePath));
+            }
+            catch {
+                return undefined;
+            }
+        },
+        listDirectory: async (absoluteDir) => {
+            try {
+                return [...(await adapter.listFolder(absoluteDir))];
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
+/**
+ * Discovers every pack under `folders`, engine-gated against
+ * `engine` (the host's renderer engine id, given by the caller) — the same
+ * posture a renderer's pack loader takes for an unsupported `engine`, so
+ * neither Insert Component nor completion ever offers a component this
+ * renderer could not render.
+ */
+export async function discoverConfiguredPacks(folders, io, engine) {
+    const result = await discoverPacks(folders, io.readFile, io.listDirectory, engine);
+    const components = [
+        ...result.packs.flatMap((pack) => declaredPackComponents(pack.manifest)),
+        ...result.skipped.flatMap((entry) => entry.engineUnsupported?.components ?? []),
+    ];
+    return {
+        packs: result.packs,
+        skipped: result.skipped,
+        namespaces: installedNamespaces(result.packs),
+        components,
+        unavailable: componentsWithoutEngineView(components, engine),
+    };
+}
+/**
+ * Runs `discoverConfiguredPacks` over `source.authorizedFolders()`. The
+ * caller (`createMarkiiHost`'s `loadPacks`) checks that
+ * `adapter.packs` exists before calling this — a host with no `packs`
+ * capability at all returns `Unsupported` first and never reaches here.
+ */
+export async function loadPacksViaAdapter(source, io) {
+    const folders = await source.authorizedFolders();
+    return discoverConfiguredPacks(folders, io, source.engine);
+}

package/dist/host/pack-remove.d.ts

@@ -0,0 +1,21 @@
+import type { HostAdapter } from './adapter.js';
+export type RemovePackOutcome = {
+    readonly kind: 'removed';
+    readonly namespace: string;
+} | {
+    readonly kind: 'not-installed';
+    readonly namespace: string;
+} | {
+    readonly kind: 'reserved';
+    readonly namespace: string;
+} | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+/** Never throws. The caller checks `adapter.packs.installRoot`/`removeFolder` exist first. */
+export declare function removePackViaAdapter(adapter: HostAdapter, namespace: string, installRoot: string, removeFolder: (folder: string) => Promise<void>, reservedNamespaces: ReadonlySet<string>): Promise<RemovePackOutcome>;
+export declare function removePackMessage(outcome: RemovePackOutcome): string;
+export declare function removePackDiagnosticLine(outcome: RemovePackOutcome): string;

package/dist/host/pack-remove.js

@@ -0,0 +1,65 @@
+/**
+ * Removing an installed pack: the one shared behavior behind a host's
+ * "remove pack" command. The install root holds one folder per namespace
+ * (`pack-install.ts`), so removal is a path join, a reserved-namespace
+ * check, and `HostPackSource.removeFolder`. Nothing outside the install
+ * root is ever touched: the namespace is validated as a pack name (no
+ * separators, no dots) before any path is built.
+ */
+import { joinPath } from '../path-util.js';
+import { validatePackName } from '@markii/pack';
+/** Never throws. The caller checks `adapter.packs.installRoot`/`removeFolder` exist first. */
+export async function removePackViaAdapter(adapter, namespace, installRoot, removeFolder, reservedNamespaces) {
+    const valid = validatePackName(namespace);
+    if (!valid.ok) {
+        return {
+            kind: 'invalid',
+            reason: `"${namespace}" is not a valid pack namespace`,
+        };
+    }
+    if (reservedNamespaces.has(namespace)) {
+        return { kind: 'reserved', namespace };
+    }
+    const folder = joinPath(installRoot, namespace);
+    try {
+        if (!(await adapter.exists(folder))) {
+            return { kind: 'not-installed', namespace };
+        }
+        await removeFolder(folder);
+    }
+    catch (err) {
+        return {
+            kind: 'failed',
+            reason: `could not remove pack "${namespace}": ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    return { kind: 'removed', namespace };
+}
+export function removePackMessage(outcome) {
+    switch (outcome.kind) {
+        case 'removed':
+            return `Markii: removed pack "${outcome.namespace}".`;
+        case 'not-installed':
+            return `Markii: no pack named "${outcome.namespace}" is installed. Nothing was removed.`;
+        case 'reserved':
+            return `Markii: "${outcome.namespace}" is built in and cannot be removed. Nothing was removed.`;
+        case 'invalid':
+            return `Markii: ${outcome.reason}. Nothing was removed.`;
+        case 'failed':
+            return `Markii: ${outcome.reason}.`;
+    }
+}
+export function removePackDiagnosticLine(outcome) {
+    switch (outcome.kind) {
+        case 'removed':
+            return `Remove pack removed "${outcome.namespace}".`;
+        case 'not-installed':
+            return `Remove pack found no installed pack "${outcome.namespace}"; nothing was removed.`;
+        case 'reserved':
+            return `Remove pack refused "${outcome.namespace}": a built-in pack cannot be removed.`;
+        case 'invalid':
+            return `Remove pack refused: ${outcome.reason}.`;
+        case 'failed':
+            return `Remove pack failed: ${outcome.reason}`;
+    }
+}

package/dist/host/pack-trust-behavior.d.ts

@@ -0,0 +1,79 @@
+import type { PackTrustList } from '../packs/pack-trust.js';
+import type { HostAdapter } from './adapter.js';
+/** One installed pack this device has enabled. */
+export interface EnabledPack {
+    readonly namespace: string;
+    /** Absolute folder under the install root. */
+    readonly folder: string;
+    /** The version recorded in the trust list, when the pack declared one. */
+    readonly version?: string;
+}
+export interface InstalledPacksListing {
+    /** Folders in the install root whose namespace this device trusts. */
+    readonly enabled: readonly EnabledPack[];
+    /** Folders in the install root this device does not trust: present, never loaded. */
+    readonly notEnabled: readonly string[];
+}
+/** Whether this adapter's pack source gates installed packs on the device trust list and can say where they live. */
+export declare function usesPackTrust(adapter: HostAdapter): boolean;
+export declare function readPackTrust(adapter: HostAdapter): PackTrustList;
+/**
+ * Pure: splits the namespaces found in the install root by the trust
+ * list. A trust entry naming a namespace no longer on disk contributes to
+ * neither side: there is nothing to load and nothing to report.
+ */
+export declare function selectEnabledPacks(installRoot: string, onDiskNamespaces: readonly string[], trust: PackTrustList): InstalledPacksListing;
+/** Lists the install root through the adapter and splits it by trust. A host without trust returns everything as neither: callers check `usesPackTrust` first. Never throws. */
+export declare function listInstalledPacks(adapter: HostAdapter): Promise<InstalledPacksListing>;
+/** The folders the trust gate lets load, for `authorizedFolders` to be extended with. Empty for a host that does not use trust. */
+export declare function trustedPackFolders(adapter: HostAdapter): Promise<readonly string[]>;
+/**
+ * Called by the install path after an archive was extracted: records the
+ * namespace as trusted on this device. A no-op for a host without trust.
+ * Never throws; a refused write is reported on the diagnostics surface.
+ */
+export declare function trustInstalledPack(adapter: HostAdapter, namespace: string, installedDir: string): Promise<void>;
+export type EnablePackOutcome = {
+    readonly kind: 'enabled';
+    readonly namespace: string;
+} | {
+    readonly kind: 'declined';
+    readonly namespace: string;
+} | {
+    readonly kind: 'not-installed';
+    readonly namespace: string;
+} | {
+    readonly kind: 'reserved';
+    readonly namespace: string;
+} | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+export type DisablePackOutcome = {
+    readonly kind: 'disabled';
+    readonly namespace: string;
+} | {
+    readonly kind: 'not-enabled';
+    readonly namespace: string;
+} | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+/** Never throws. The caller checks `usesPackTrust` first. */
+export declare function enablePackViaAdapter(adapter: HostAdapter, namespace: string): Promise<EnablePackOutcome>;
+/** Never throws. The caller checks `usesPackTrust` first. The folder stays on disk. */
+export declare function disablePackViaAdapter(adapter: HostAdapter, namespace: string): Promise<DisablePackOutcome>;
+/** Withdraws a namespace's trust entry after a removal. A no-op for a host without trust. Never throws. */
+export declare function forgetPackTrust(adapter: HostAdapter, namespace: string): Promise<void>;
+export declare function enablePackMessage(outcome: EnablePackOutcome): string;
+export declare function enablePackDiagnosticLine(outcome: EnablePackOutcome): string;
+export declare function disablePackMessage(outcome: DisablePackOutcome): string;
+export declare function disablePackDiagnosticLine(outcome: DisablePackOutcome): string;
+/** One line per folder that is present in the install root but not enabled on this device. Informational, not a failure. */
+export declare function notEnabledPackDiagnosticLine(namespace: string, deviceNoun: string): string;