@peers-app/peers-sdk 0.26.3 → 0.26.5

package/dist/contracts/system/packages-contract.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGES_CONTRACT_VERSION = void 0;
+exports.packageVersionPromotionTargets = packageVersionPromotionTargets;
+exports.isPackageRepositoryUrl = isPackageRepositoryUrl;
+exports.getPackagesContractDefinition = getPackagesContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Packages contract. */
+exports.PACKAGES_CONTRACT_VERSION = 1;
+/**
+ * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
+ * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
+ * matching the Versions screen. Promotion never demotes.
+ *
+ * @param versionTag - The version's current tag.
+ */
+function packageVersionPromotionTargets(versionTag) {
+    switch (versionTag || "dev") {
+        case "dev":
+            return ["beta", "stable"];
+        case "beta":
+            return ["stable"];
+        default:
+            return [];
+    }
+}
+/**
+ * Whether user input names a remote repository for `clonePackage` (`http(s)://` or
+ * `git@host:`) rather than a local folder or package name. The host still validates the
+ * URL; this only routes input in the CLI and UI the same way.
+ *
+ * @param target - Input as typed.
+ */
+function isPackageRepositoryUrl(target) {
+    return /^(https?:\/\/|git@[^:/\s]+:)/.test(target.trim());
+}
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+const packageIdField = field("packageId", field_type_1.FieldType.id, "Package id.");
+const operationResultFields = [
+    packageIdField,
+    field("created", field_type_1.FieldType.boolean, "True when a new package was scaffolded.", {
+        optional: true,
+    }),
+    field("warning", field_type_1.FieldType.string, "Non-fatal problem to show the caller.", { optional: true }),
+    field("package", field_type_1.FieldType.object, "The package after the operation."),
+];
+let definition;
+/**
+ * Return the System Packages contract shape.
+ *
+ * Tools carry no `remoteAccessLevel`, so only callers this device trusts as `Self` (the
+ * user's own devices and users explicitly granted Self) can reach them remotely; group
+ * members, Admins included, are refused. Package code and workflows are refused
+ * everywhere. The provider binds every call to the route's
+ * data context; a package's group is the data boundary. Tools the host cannot perform
+ * throw `System Packages <tool> is not supported on this host (...)`; `getCapabilities`
+ * reports support up front.
+ */
+function getPackagesContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.packagesContractId,
+        version: exports.PACKAGES_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Packages",
+        description: "Install, inspect, reload, activate, and uninstall packages, with each device's observed runtime state.",
+        tables: [],
+        tools: [
+            {
+                name: "getCapabilities",
+                usageDescription: "Report which package operations this host supports.",
+                inputFields: [],
+                outputFields: [field("capabilities", field_type_1.FieldType.object, "Supported operations.")],
+            },
+            {
+                name: "listPackages",
+                usageDescription: "List packages in this data context with their requested version and runtime state on this device.",
+                inputFields: [],
+                outputFields: [
+                    field("packages", field_type_1.FieldType.object, "Package summaries.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getPackage",
+                usageDescription: "Return one package with its versions, local folder, and runtime state.",
+                inputFields: [packageIdField],
+                outputFields: [field("package", field_type_1.FieldType.object, "Package details.")],
+            },
+            {
+                name: "importPackage",
+                usageDescription: "Import an existing package folder on this device and load it.",
+                inputFields: [
+                    field("path", field_type_1.FieldType.string, "Absolute or ~-prefixed folder path on the host."),
+                    field("name", field_type_1.FieldType.string, "Display name; defaults to package.json.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "createPackage",
+                usageDescription: "Scaffold a new package from the template, or import the folder when it already exists.",
+                inputFields: [
+                    field("name", field_type_1.FieldType.string, "Package display name."),
+                    field("location", field_type_1.FieldType.string, "Folder; defaults to the packages directory.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "clonePackage",
+                usageDescription: "Clone a package repository, build it, and import it.",
+                inputFields: [field("url", field_type_1.FieldType.string, "Git repository URL.")],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "installPackage",
+                usageDescription: "Re-enable a disabled package, or copy one here from another of your data contexts, then load it.",
+                inputFields: [
+                    packageIdField,
+                    field("fromDataContextId", field_type_1.FieldType.id, "Context to copy from; searched when omitted.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "activatePackageVersion",
+                usageDescription: "Select a stored version for this device or the whole group, then load it on this device.",
+                inputFields: [
+                    packageIdField,
+                    field("packageVersionId", field_type_1.FieldType.id, "Version to activate; omit with device scope to follow the group again.", { optional: true }),
+                    field("scope", field_type_1.FieldType.string, "device (default) or group.", { optional: true }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "reloadPackage",
+                usageDescription: "Rebuild the dev version from the package folder when it changed, then force-reload the package on this device.",
+                inputFields: [packageIdField],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "reloadAllPackages",
+                usageDescription: "Re-read every package folder on this device and reload the packages whose bundles changed.",
+                inputFields: [],
+                outputFields: [
+                    field("skipped", field_type_1.FieldType.string, "Why the host skipped the reload.", {
+                        optional: true,
+                    }),
+                    field("results", field_type_1.FieldType.object, "Per-package outcomes.", { isArray: true }),
+                ],
+            },
+            {
+                name: "linkRemoteRepo",
+                usageDescription: "Create a remote repository for a local package and link it.",
+                inputFields: [packageIdField],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "uninstallPackage",
+                usageDescription: "Remove a package from this data context for every member device and unload it here. Versions, files, and device preferences are kept.",
+                inputFields: [packageIdField],
+                outputFields: [
+                    packageIdField,
+                    field("removed", field_type_1.FieldType.boolean, "True when the package row was removed."),
+                ],
+            },
+            {
+                name: "promotePackageVersion",
+                usageDescription: "Promote a stored package version to beta or stable (dev to beta or stable, beta to stable). Re-signs it with the package author key when this device has it, records the promotion in its history, and activates it when this device was running it and the group follows the new tag.",
+                inputFields: [
+                    field("packageVersionId", field_type_1.FieldType.id, "Version to promote."),
+                    field("versionTag", field_type_1.FieldType.string, "New release channel: beta or stable."),
+                ],
+                outputFields: [
+                    ...operationResultFields,
+                    field("packageVersionId", field_type_1.FieldType.id, "Promoted version."),
+                    field("version", field_type_1.FieldType.string, "Its version number."),
+                    field("versionTag", field_type_1.FieldType.string, "Its new release channel."),
+                    field("signed", field_type_1.FieldType.boolean, "True when this device signed the promoted version."),
+                    field("activated", field_type_1.FieldType.boolean, "True when the promotion also activated the version for the group or this device."),
+                ],
+            },
+            {
+                name: "installDefaultPackages",
+                usageDescription: "Install the default packages into this data context.",
+                inputFields: [],
+                outputFields: [
+                    field("installed", field_type_1.FieldType.boolean, "True when anything was installed or updated."),
+                ],
+            },
+        ],
+        observables: [
+            {
+                name: "runtimeStates",
+                description: "Runtime state of this context's packages on this device, keyed by package id.",
+                valueType: field_type_1.FieldType.object,
+                writable: false,
+            },
+        ],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.packagesContractId,
+    version: exports.PACKAGES_CONTRACT_VERSION,
+    getDefinition: getPackagesContractDefinition,
+});

package/dist/data/create-group.d.ts

@@ -19,6 +19,6 @@ export declare const GROUP_NAME_MAX_LENGTH = 100;
  *
  * Runs on a host with signing enabled (`GroupsTable.enableGroupSigning`); UIs reach it
  * through the host rather than duplicating the steps. Package seeding for the new context
- * (for example `seedBundledPeersCore`) is the caller's responsibility.
+ * (for example System Packages `installDefaultPackages`) is the caller's responsibility.
  */
 export declare function createGroup(userContext: UserContext, input: CreateGroupInput): Promise<IGroup>;

package/dist/data/create-group.js

@@ -20,7 +20,7 @@ exports.GROUP_NAME_MAX_LENGTH = 100;
  *
  * Runs on a host with signing enabled (`GroupsTable.enableGroupSigning`); UIs reach it
  * through the host rather than duplicating the steps. Package seeding for the new context
- * (for example `seedBundledPeersCore`) is the caller's responsibility.
+ * (for example System Packages `installDefaultPackages`) is the caller's responsibility.
  */
 async function createGroup(userContext, input) {
     const name = input.name.trim();

package/dist/data/package-version-resolver.d.ts

@@ -81,17 +81,23 @@ export interface IResolveResult {
 }
 /**
  * Core resolver: evaluates available package versions against the device's
- * follow policy and loads the best one. Never auto-activates dev versions
- * unless the device explicitly follows "dev".
+ * follow policy and loads the best one. A dev version runs only on a device whose own
+ * selection points at it; a group selection of a dev version is left unloaded here.
  *
  * Callers:
  * - `PackagesTrackedDataSource.applyChanges` (on sync)
  * - `PackageLoader.loadAllPackages` (startup)
  * - `package-installer.ts` (after saving new bundles)
+ *
+ * @param opts.force - Reload even when the package is already loaded.
+ * @param opts.localPath - Package folder whose rebuilt dev bundle wins over the stored one.
+ * @param opts.onlyIfChanged - With `force`, keep a running package whose selected version and
+ *   bundle are unchanged instead of restarting it (sync reconciliation).
  */
 export declare function resolveDevicePackageVersion(pkg: IPackage, dataContext: DataContext, opts?: {
     force?: boolean;
     localPath?: string;
+    onlyIfChanged?: boolean;
 }): Promise<IResolveResult>;
 /**
  * Returns true when the device has an explicit follow-policy override

package/dist/data/package-version-resolver.js

@@ -85,13 +85,18 @@ function getEffectivePackagePrefs(pkg, devicePrefs) {
 }
 /**
  * Core resolver: evaluates available package versions against the device's
- * follow policy and loads the best one. Never auto-activates dev versions
- * unless the device explicitly follows "dev".
+ * follow policy and loads the best one. A dev version runs only on a device whose own
+ * selection points at it; a group selection of a dev version is left unloaded here.
  *
  * Callers:
  * - `PackagesTrackedDataSource.applyChanges` (on sync)
  * - `PackageLoader.loadAllPackages` (startup)
  * - `package-installer.ts` (after saving new bundles)
+ *
+ * @param opts.force - Reload even when the package is already loaded.
+ * @param opts.localPath - Package folder whose rebuilt dev bundle wins over the stored one.
+ * @param opts.onlyIfChanged - With `force`, keep a running package whose selected version and
+ *   bundle are unchanged instead of restarting it (sync reconciliation).
  */
 async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     const pvar = packagePrefsVar(pkg.packageId, dataContext);
@@ -118,6 +123,21 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     if (!effectiveActivePvId) {
         return { loaded: false, upgraded: false };
     }
+    // A dev version runs only on a device that activated it. The group's selection can be a
+    // dev version (a new package, or one copied from another context); other devices leave it
+    // unloaded until they activate it themselves. Once activated here, rebuilds of that same
+    // version row keep loading through the dev branch below.
+    if (rawPrefs.activePackageVersionId !== effectiveActivePvId) {
+        const groupSelection = await (0, package_versions_1.PackageVersions)(dataContext)
+            .get(effectiveActivePvId)
+            .catch(() => undefined);
+        if (groupSelection?.versionTag === "dev") {
+            await dataContext.packageLoader.unloadPackage(pkg.packageId, {
+                reason: `Only a dev version (v${groupSelection.version}) is selected; activate it on this device to run it`,
+            });
+            return { loaded: false, pv: groupSelection, upgraded: false };
+        }
+    }
     const localPath = opts?.localPath ??
         (await readStoredPackageLocalPath(pkg.packageId, dataContext).catch(() => undefined));
     const compatibilityTargetId = rawPrefs.compatibilityFallbackForPackageVersionId;
@@ -130,6 +150,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         if (compatibilityTarget) {
             try {
                 const restored = await dataContext.packageLoader.loadPackage(pkg, {
+                    onlyIfChanged: opts?.onlyIfChanged,
                     force: true,
                     localPath,
                     packageVersionId: compatibilityTargetId,
@@ -158,6 +179,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         if (!pv)
             return { loaded: false, pv: undefined, upgraded: false };
         const instance = await dataContext.packageLoader.loadPackage(pkg, {
+            onlyIfChanged: opts?.onlyIfChanged,
             force: opts?.force,
             localPath,
             packageVersionId: effectiveActivePvId,
@@ -182,6 +204,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     // activates a non-dev version.
     if (activePv?.versionTag === "dev") {
         const instance = await dataContext.packageLoader.loadPackage(pkg, {
+            onlyIfChanged: opts?.onlyIfChanged,
             force: opts?.force,
             localPath,
             packageVersionId: effectiveActivePvId,
@@ -216,6 +239,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     if (!bestPv || bestPv.packageVersionId === effectiveActivePvId) {
         if (activePv) {
             const instance = await dataContext.packageLoader.loadPackage(pkg, {
+                onlyIfChanged: opts?.onlyIfChanged,
                 force: opts?.force,
                 localPath,
                 packageVersionId: effectiveActivePvId,
@@ -233,6 +257,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     // A better PV was found - attempt to load it (getFileContents will
     // auto-download missing chunks from peers)
     const instance = await dataContext.packageLoader.loadPackage(pkg, {
+        onlyIfChanged: opts?.onlyIfChanged,
         force: true,
         localPath,
         packageVersionId: bestPv.packageVersionId,
@@ -241,6 +266,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         // Bundle unavailable even after download attempt - keep current version
         if (activePv) {
             const fallbackInstance = await dataContext.packageLoader.loadPackage(pkg, {
+                onlyIfChanged: opts?.onlyIfChanged,
                 force: opts?.force,
                 localPath,
                 packageVersionId: effectiveActivePvId,

package/dist/data/package-version-resolver.test.js

@@ -368,6 +368,48 @@ describe("resolveDevicePackageVersion — expected behavior (control)", () => {
         expect(loadedPvIds).toContain(stablePv.packageVersionId);
         expect(loadedPvIds).not.toContain(devPv.packageVersionId);
     });
+    it.each([
+        ["no prefs", false],
+        ["a pin", true],
+    ])("leaves a group-selected dev version unloaded on a device with %s", async (_label, pinned) => {
+        const dc = freshGroupDc();
+        const packageId = (0, utils_1.newid)();
+        const devPv = makePV(packageId, { version: "0.1.0", versionTag: "dev" });
+        await (0, package_versions_1.PackageVersions)(dc).save(devPv);
+        const pkg = makePkg({ packageId, activePackageVersionId: devPv.packageVersionId });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        if (pinned)
+            await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { pinned: true }, dc);
+        const load = jest.spyOn(dc.packageLoader, "loadPackage");
+        const unload = jest
+            .spyOn(dc.packageLoader, "unloadPackage")
+            .mockImplementation(async () => undefined);
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result).toMatchObject({ loaded: false, upgraded: false });
+        expect(result.pv?.packageVersionId).toBe(devPv.packageVersionId);
+        expect(load).not.toHaveBeenCalled();
+        expect(unload).toHaveBeenCalledWith(packageId, {
+            reason: "Only a dev version (v0.1.0) is selected; activate it on this device to run it",
+        });
+    });
+    it("runs a group-selected dev version once this device activates it", async () => {
+        const dc = freshGroupDc();
+        const packageId = (0, utils_1.newid)();
+        const devPv = makePV(packageId, { version: "0.1.0", versionTag: "dev" });
+        await (0, package_versions_1.PackageVersions)(dc).save(devPv);
+        const pkg = makePkg({ packageId, activePackageVersionId: devPv.packageVersionId });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { activePackageVersionId: devPv.packageVersionId }, dc);
+        const loadedPvIds = [];
+        jest.spyOn(dc.packageLoader, "loadPackage").mockImplementation(async (_pkg, opts) => {
+            if (opts?.packageVersionId)
+                loadedPvIds.push(opts.packageVersionId);
+            return { packageId };
+        });
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result.loaded).toBe(true);
+        expect(loadedPvIds).toEqual([devPv.packageVersionId]);
+    });
     it("installs assistants and workflows into the data context on auto-upgrade", async () => {
         const dc = groupDc();
         const packageId = (0, utils_1.newid)();

package/dist/package-installer/package-author-signer.d.ts

@@ -23,3 +23,22 @@ export declare function loadPackageSigningKey(packageId: string, getUserSecretKe
  * @param getUserSecretKey - Platform callback that returns the signed-in user's secret key
  */
 export declare function trySignPackageAuthorVersion(pvFields: AuthorSignableFields, getUserSecretKey: () => Promise<string>): Promise<string | undefined>;
+/** Host-installed signer for PackageVersion author signatures. */
+export type PackageAuthorVersionSigner = (pvFields: AuthorSignableFields) => Promise<string | undefined>;
+/**
+ * Install (or clear) the host's PackageVersion author signer.
+ *
+ * `peers-device` installs one at startup over the signed-in user's secret key, so Runtime
+ * code (the installer, System Packages) can re-sign versions without a host RPC.
+ *
+ * @param signer - Signer to use, or `undefined` to clear it.
+ */
+export declare function setPackageAuthorVersionSigner(signer: PackageAuthorVersionSigner | undefined): void;
+/**
+ * Sign PackageVersion fields with the installed host signer.
+ *
+ * @param pvFields - Author-signable PackageVersion fields.
+ * @returns The detached signature, or `undefined` when no signer is installed, the package
+ *   signing key is unavailable, or signing fails.
+ */
+export declare function signPackageAuthorVersionOnHost(pvFields: AuthorSignableFields): Promise<string | undefined>;

package/dist/package-installer/package-author-signer.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPackageSigningKey = loadPackageSigningKey;
 exports.trySignPackageAuthorVersion = trySignPackageAuthorVersion;
+exports.setPackageAuthorVersionSigner = setPackageAuthorVersionSigner;
+exports.signPackageAuthorVersionOnHost = signPackageAuthorVersionOnHost;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const persistent_vars_1 = require("../data/persistent-vars");
 const keys_1 = require("../keys");
@@ -55,3 +57,25 @@ async function trySignPackageAuthorVersion(pvFields, getUserSecretKey) {
         return undefined;
     }
 }
+let installedSigner;
+/**
+ * Install (or clear) the host's PackageVersion author signer.
+ *
+ * `peers-device` installs one at startup over the signed-in user's secret key, so Runtime
+ * code (the installer, System Packages) can re-sign versions without a host RPC.
+ *
+ * @param signer - Signer to use, or `undefined` to clear it.
+ */
+function setPackageAuthorVersionSigner(signer) {
+    installedSigner = signer;
+}
+/**
+ * Sign PackageVersion fields with the installed host signer.
+ *
+ * @param pvFields - Author-signable PackageVersion fields.
+ * @returns The detached signature, or `undefined` when no signer is installed, the package
+ *   signing key is unavailable, or signing fails.
+ */
+async function signPackageAuthorVersionOnHost(pvFields) {
+    return installedSigner?.(pvFields);
+}

package/dist/package-installer/package-creator.d.ts

@@ -1,11 +1,5 @@
 import type { DataContext } from "../context/data-context";
-import type { IAddOrUpdatePackageResult, ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps, ITemplateCacheResult, TemplateCacheRefreshFailure } from "./types";
-/**
- * Normalize `addOrUpdatePackage` RPC results.
- * Older hosts return a bare packageId string; current hosts return
- * {@link IAddOrUpdatePackageResult}.
- */
-export declare function unwrapAddOrUpdatePackageResult(result: string | IAddOrUpdatePackageResult): IAddOrUpdatePackageResult;
+import type { ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps, ITemplateCacheResult, TemplateCacheRefreshFailure } from "./types";
 /**
  * Convert a human-readable package name to a filesystem-safe folder slug.
  * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"

package/dist/package-installer/package-creator.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unwrapAddOrUpdatePackageResult = unwrapAddOrUpdatePackageResult;
 exports.nameToFolderSlug = nameToFolderSlug;
 exports.classifyTemplatePullFailure = classifyTemplatePullFailure;
 exports.ensureTemplateCache = ensureTemplateCache;
@@ -24,17 +23,6 @@ function patchTemplateTokens(contents, values) {
         .replaceAll("<app-screen-id>", values.appScreenId)
         .replaceAll("<contract-id>", values.contractId);
 }
-/**
- * Normalize `addOrUpdatePackage` RPC results.
- * Older hosts return a bare packageId string; current hosts return
- * {@link IAddOrUpdatePackageResult}.
- */
-function unwrapAddOrUpdatePackageResult(result) {
-    if (typeof result === "string") {
-        return { packageId: result };
-    }
-    return result;
-}
 /**
  * Convert a human-readable package name to a filesystem-safe folder slug.
  * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"

package/dist/package-installer/package-creator.test.js

@@ -87,22 +87,6 @@ beforeEach(() => {
     mockNewKeys.mockReturnValue(generatedKeys);
     mockPersistentVarsSave.mockReset();
 });
-describe("unwrapAddOrUpdatePackageResult", () => {
-    it("accepts a legacy packageId string", () => {
-        expect((0, package_creator_1.unwrapAddOrUpdatePackageResult)("00mnkoyo7mizav6tseubjzr3a")).toEqual({
-            packageId: "00mnkoyo7mizav6tseubjzr3a",
-        });
-    });
-    it("passes through a structured result including a template warning", () => {
-        expect((0, package_creator_1.unwrapAddOrUpdatePackageResult)({
-            packageId: "00mnkoyo7mizav6tseubjzr3a",
-            warning: "stale template",
-        })).toEqual({
-            packageId: "00mnkoyo7mizav6tseubjzr3a",
-            warning: "stale template",
-        });
-    });
-});
 describe("nameToFolderSlug", () => {
     it("converts a simple name", () => {
         expect((0, package_creator_1.nameToFolderSlug)("My Widget")).toBe("my-widget");

package/dist/package-installer/package-installer.d.ts

@@ -8,6 +8,11 @@ import type { IInstallOpts, IInstallResult, IPackageInfo, IPackageInstallerDeps
  * bundles from `dist/`, hashes them for deduplication, saves File records
  * only when content has changed, upserts the PackageVersion, and optionally
  * triggers the package loader and device version resolution.
+ *
+ * When the bundle hash matches the existing PackageVersion, no files or PV are
+ * rewritten. The Packages row still gets a missing `activePackageVersionId`
+ * (and description), and when the id was missing the version is activated on
+ * this device unless `skipResolve`.
  */
 export declare function installPackageFromBundles(dataContext: DataContext, deps: IPackageInstallerDeps, packageId: string, opts?: IInstallOpts): Promise<IInstallResult>;
 /**