@peers-app/peers-sdk 0.18.8 → 0.19.6

package/dist/data/packages.d.ts

@@ -9,26 +9,11 @@ declare const schema: z.ZodObject<{
     createdBy: z.ZodEffects<z.ZodString, string, string>;
     disabled: z.ZodOptional<z.ZodBoolean>;
     remoteRepo: z.ZodOptional<z.ZodString>;
-    /** @deprecated Read appNavs from the active IPackageVersion record instead. */
-    appNavs: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        displayName: z.ZodOptional<z.ZodString>;
-        iconClassName: z.ZodString;
-        navigationPath: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        iconClassName: string;
-        navigationPath: string;
-        displayName?: string | undefined;
-    }, {
-        name: string;
-        iconClassName: string;
-        navigationPath: string;
-        displayName?: string | undefined;
-    }>, "many">>;
     activePackageVersionId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     versionFollowRange: z.ZodOptional<z.ZodEnum<["pinned", "patch", "minor", "latest"]>>;
     followVersionTags: z.ZodOptional<z.ZodString>;
+    updateUrl: z.ZodOptional<z.ZodString>;
+    publishPublicKey: z.ZodString;
     signature: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     name: string;
@@ -36,34 +21,26 @@ declare const schema: z.ZodObject<{
     signature: string;
     packageId: string;
     createdBy: string;
+    publishPublicKey: string;
     disabled?: boolean | undefined;
-    appNavs?: {
-        name: string;
-        iconClassName: string;
-        navigationPath: string;
-        displayName?: string | undefined;
-    }[] | undefined;
     remoteRepo?: string | undefined;
     activePackageVersionId?: string | undefined;
     versionFollowRange?: "pinned" | "patch" | "minor" | "latest" | undefined;
     followVersionTags?: string | undefined;
+    updateUrl?: string | undefined;
 }, {
     name: string;
     description: string;
     signature: string;
     packageId: string;
     createdBy: string;
+    publishPublicKey: string;
     disabled?: boolean | undefined;
-    appNavs?: {
-        name: string;
-        iconClassName: string;
-        navigationPath: string;
-        displayName?: string | undefined;
-    }[] | undefined;
     remoteRepo?: string | undefined;
     activePackageVersionId?: string | undefined;
     versionFollowRange?: "pinned" | "patch" | "minor" | "latest" | undefined;
     followVersionTags?: string | undefined;
+    updateUrl?: string | undefined;
 }>;
 export type IPackage = z.infer<typeof schema>;
 export declare class PackagesTable extends Table<IPackage> {

package/dist/data/packages.js

@@ -38,7 +38,6 @@ exports.autoUpdatePeersCore = exports.reloadPackagesOnPageRefresh = exports.pack
 exports.Packages = Packages;
 const zod_1 = require("zod");
 const context_1 = require("../context");
-const app_nav_1 = require("../types/app-nav");
 const zod_types_1 = require("../types/zod-types");
 const decorators_1 = require("./orm/decorators");
 const table_1 = require("./orm/table");
@@ -56,11 +55,6 @@ const schema = zod_1.z.object({
         .optional()
         .describe("Whether the package's components should be loaded and included in the app runtime"),
     remoteRepo: zod_1.z.string().optional().describe("The remote repository where the package is stored"),
-    /** @deprecated Read appNavs from the active IPackageVersion record instead. */
-    appNavs: app_nav_1.appNavSchema
-        .array()
-        .optional()
-        .describe("DEPRECATED: Read appNavs from the active IPackageVersion record instead"),
     activePackageVersionId: zod_types_1.zodPeerId
         .optional()
         .describe("FK to PackageVersions — the currently active version"),
@@ -72,6 +66,14 @@ const schema = zod_1.z.object({
         .string()
         .optional()
         .describe('Tag policy: undefined="current" (follow active tag), "*"=any tag, or CSV like "stable,prod"'),
+    updateUrl: zod_1.z
+        .string()
+        .optional()
+        .describe("Base URL for remote package seeding. Admin devices check <updateUrl>/latest-<tag>.json on startup."),
+    publishPublicKey: zod_1.z
+        .string()
+        .describe("Ed25519 public key (base64url) of the package publisher. " +
+        "Set at package creation; used as TOFU anchor for verifying packageAuthorSignature on versions."),
     signature: zod_1.z.string().describe("The signed hash of this data excluding the signature itself"),
 });
 const metaData = {

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./keys";
 export * from "./logging";
 export * from "./mentions";
 export * from "./observable";
+export * from "./package-installer";
 export * from "./package-loader";
 export * from "./peers-ui/peers-ui";
 export * from "./peers-ui/peers-ui.types";

package/dist/index.js

@@ -40,6 +40,7 @@ __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./mentions"), exports);
 __exportStar(require("./observable"), exports);
+__exportStar(require("./package-installer"), exports);
 __exportStar(require("./package-loader"), exports);
 __exportStar(require("./peers-ui/peers-ui"), exports);
 __exportStar(require("./peers-ui/peers-ui.types"), exports);

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

@@ -0,0 +1,10 @@
+export * from "./package-author-signing";
+export * from "./package-cloner";
+export * from "./package-creator";
+export * from "./package-installer";
+export * from "./package-propagation";
+export * from "./package-publisher";
+export * from "./package-remote-checker";
+export * from "./package-seed-installer";
+export * from "./package-tarball";
+export * from "./types";

package/dist/package-installer/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./package-author-signing"), exports);
+__exportStar(require("./package-cloner"), exports);
+__exportStar(require("./package-creator"), exports);
+__exportStar(require("./package-installer"), exports);
+__exportStar(require("./package-propagation"), exports);
+__exportStar(require("./package-publisher"), exports);
+__exportStar(require("./package-remote-checker"), exports);
+__exportStar(require("./package-seed-installer"), exports);
+__exportStar(require("./package-tarball"), exports);
+__exportStar(require("./types"), exports);

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

@@ -0,0 +1,54 @@
+import type { IPackageVersion } from "../data/package-versions";
+import type { IAppNav } from "../types/app-nav";
+/** Prefix for the persistent variable name that stores a package's signing secret key. */
+export declare const PACKAGE_SIGNING_KEY_PREFIX = "packageSigningKey_";
+/**
+ * The subset of PackageVersion fields that the publisher signs.
+ * The `publicKey` field is included so verifiers know which key to check against.
+ */
+export interface IAuthorSignedPayload {
+    packageId: string;
+    packageVersionId: string;
+    version: string;
+    versionTag: string;
+    packageBundleFileHash: string;
+    routesBundleFileHash?: string;
+    uiBundleFileHash?: string;
+    publicKey: string;
+    appNavs?: IAppNav[];
+    createdBy?: string;
+    createdAt?: string;
+}
+/** PV fields required by {@link buildAuthorSignedPayload} and related signing/verification functions. */
+export type AuthorSignableFields = Pick<IPackageVersion, "packageId" | "packageVersionId" | "version" | "versionTag" | "packageBundleFileHash" | "routesBundleFileHash" | "uiBundleFileHash" | "appNavs"> & Partial<Pick<IPackageVersion, "createdBy" | "createdAt">>;
+/**
+ * Extracts the signable payload from a PackageVersion record.
+ * Only includes optional fields when they have a value (undefined fields are omitted
+ * entirely so `stableStringify` produces a consistent output).
+ */
+export declare function buildAuthorSignedPayload(pv: AuthorSignableFields, publicKey: string): IAuthorSignedPayload;
+/**
+ * Signs a PackageVersion with the publisher's Ed25519 secret key.
+ * @returns A base64url-encoded detached Ed25519 signature over `stableStringify(payload)`.
+ */
+export declare function signPackageAuthor(pv: AuthorSignableFields, secretKey: string): string;
+/**
+ * Result of verifying a packageAuthorSignature.
+ * `publicKey` is the key embedded in the payload (extracted from the signature verification process).
+ */
+export interface IVerifyAuthorSignatureResult {
+    valid: boolean;
+    publicKey: string;
+}
+/**
+ * Verifies the `packageAuthorSignature` on a PackageVersion record.
+ *
+ * The signature format is a raw base64url detached Ed25519 signature. The public key
+ * is NOT in the signature itself — it must be provided via `expectedPublicKey` (TOFU check)
+ * to reconstruct the payload and verify.
+ *
+ * @param pv - The PackageVersion record with `packageAuthorSignature` set
+ * @param expectedPublicKey - The public key to verify against (from Package.publishPublicKey)
+ * @returns `{ valid, publicKey }` — valid is true if signature verifies and key matches
+ */
+export declare function verifyPackageAuthorSignature(pv: AuthorSignableFields & Pick<IPackageVersion, "packageAuthorSignature">, expectedPublicKey: string): IVerifyAuthorSignatureResult;

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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_SIGNING_KEY_PREFIX = void 0;
+exports.buildAuthorSignedPayload = buildAuthorSignedPayload;
+exports.signPackageAuthor = signPackageAuthor;
+exports.verifyPackageAuthorSignature = verifyPackageAuthorSignature;
+const nacl = require("tweetnacl");
+const tweetnacl_util_1 = require("tweetnacl-util");
+const keys_1 = require("../keys");
+/** Prefix for the persistent variable name that stores a package's signing secret key. */
+exports.PACKAGE_SIGNING_KEY_PREFIX = "packageSigningKey_";
+/**
+ * Extracts the signable payload from a PackageVersion record.
+ * Only includes optional fields when they have a value (undefined fields are omitted
+ * entirely so `stableStringify` produces a consistent output).
+ */
+function buildAuthorSignedPayload(pv, publicKey) {
+    const payload = {
+        packageId: pv.packageId,
+        packageVersionId: pv.packageVersionId,
+        version: pv.version,
+        versionTag: pv.versionTag ?? "",
+        packageBundleFileHash: pv.packageBundleFileHash,
+        publicKey,
+    };
+    if (pv.routesBundleFileHash) {
+        payload.routesBundleFileHash = pv.routesBundleFileHash;
+    }
+    if (pv.uiBundleFileHash) {
+        payload.uiBundleFileHash = pv.uiBundleFileHash;
+    }
+    if (pv.appNavs) {
+        payload.appNavs = pv.appNavs;
+    }
+    if (pv.createdBy) {
+        payload.createdBy = pv.createdBy;
+    }
+    if (pv.createdAt) {
+        payload.createdAt = pv.createdAt;
+    }
+    return payload;
+}
+/**
+ * Signs a PackageVersion with the publisher's Ed25519 secret key.
+ * @returns A base64url-encoded detached Ed25519 signature over `stableStringify(payload)`.
+ */
+function signPackageAuthor(pv, secretKey) {
+    const keys = (0, keys_1.hydrateKeys)(secretKey);
+    const payload = buildAuthorSignedPayload(pv, keys.publicKey);
+    const message = (0, tweetnacl_util_1.decodeUTF8)((0, keys_1.stableStringify)(payload));
+    const sk = (0, keys_1.decodeBase64)(secretKey);
+    const signature = nacl.sign.detached(message, sk);
+    return (0, keys_1.encodeBase64)(signature);
+}
+/**
+ * Verifies the `packageAuthorSignature` on a PackageVersion record.
+ *
+ * The signature format is a raw base64url detached Ed25519 signature. The public key
+ * is NOT in the signature itself — it must be provided via `expectedPublicKey` (TOFU check)
+ * to reconstruct the payload and verify.
+ *
+ * @param pv - The PackageVersion record with `packageAuthorSignature` set
+ * @param expectedPublicKey - The public key to verify against (from Package.publishPublicKey)
+ * @returns `{ valid, publicKey }` — valid is true if signature verifies and key matches
+ */
+function verifyPackageAuthorSignature(pv, expectedPublicKey) {
+    const result = { valid: false, publicKey: expectedPublicKey };
+    if (!pv.packageAuthorSignature) {
+        return result;
+    }
+    try {
+        const payload = buildAuthorSignedPayload(pv, expectedPublicKey);
+        const message = (0, tweetnacl_util_1.decodeUTF8)((0, keys_1.stableStringify)(payload));
+        const signature = (0, keys_1.decodeBase64)(pv.packageAuthorSignature);
+        const pk = (0, keys_1.decodeBase64)(expectedPublicKey);
+        result.valid = nacl.sign.detached.verify(message, signature, pk);
+    }
+    catch {
+        result.valid = false;
+    }
+    return result;
+}

package/dist/package-installer/package-author-signing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/package-installer/package-author-signing.test.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const package_author_signing_1 = require("./package-author-signing");
+function makePV(overrides) {
+    return {
+        packageId: (0, utils_1.newid)(),
+        packageVersionId: (0, utils_1.newid)(),
+        version: "1.2.3",
+        versionTag: "stable",
+        packageBundleFileHash: "abc123hash",
+        routesBundleFileHash: "routes456hash",
+        uiBundleFileHash: "ui789hash",
+        ...overrides,
+    };
+}
+describe("package-author-signing", () => {
+    const keys = (0, keys_1.newKeys)();
+    describe("PACKAGE_SIGNING_KEY_PREFIX", () => {
+        it("has the expected value", () => {
+            expect(package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX).toBe("packageSigningKey_");
+        });
+    });
+    describe("buildAuthorSignedPayload", () => {
+        it("extracts the correct fields from a PV", () => {
+            const pv = makePV();
+            const payload = (0, package_author_signing_1.buildAuthorSignedPayload)(pv, keys.publicKey);
+            expect(payload).toEqual({
+                packageId: pv.packageId,
+                packageVersionId: pv.packageVersionId,
+                version: "1.2.3",
+                versionTag: "stable",
+                packageBundleFileHash: "abc123hash",
+                routesBundleFileHash: "routes456hash",
+                uiBundleFileHash: "ui789hash",
+                publicKey: keys.publicKey,
+            });
+        });
+        it("omits optional hash fields when undefined", () => {
+            const pv = makePV({ routesBundleFileHash: undefined, uiBundleFileHash: undefined });
+            const payload = (0, package_author_signing_1.buildAuthorSignedPayload)(pv, keys.publicKey);
+            expect(payload).not.toHaveProperty("routesBundleFileHash");
+            expect(payload).not.toHaveProperty("uiBundleFileHash");
+            expect(payload.packageBundleFileHash).toBe("abc123hash");
+        });
+        it("omits uiBundleFileHash but includes routesBundleFileHash when only ui is undefined", () => {
+            const pv = makePV({ uiBundleFileHash: undefined });
+            const payload = (0, package_author_signing_1.buildAuthorSignedPayload)(pv, keys.publicKey);
+            expect(payload.routesBundleFileHash).toBe("routes456hash");
+            expect(payload).not.toHaveProperty("uiBundleFileHash");
+        });
+        it("treats empty string versionTag the same as undefined", () => {
+            const pv = makePV({ versionTag: undefined });
+            const payload = (0, package_author_signing_1.buildAuthorSignedPayload)(pv, keys.publicKey);
+            expect(payload.versionTag).toBe("");
+        });
+    });
+    describe("signPackageAuthor + verifyPackageAuthorSignature round-trip", () => {
+        it("produces a valid signature that verifies", () => {
+            const pv = makePV();
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            expect(typeof signature).toBe("string");
+            expect(signature.length).toBeGreaterThan(0);
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, keys.publicKey);
+            expect(result.valid).toBe(true);
+            expect(result.publicKey).toBe(keys.publicKey);
+        });
+        it("works with only the required bundle hash (no routes or ui)", () => {
+            const pv = makePV({ routesBundleFileHash: undefined, uiBundleFileHash: undefined });
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, keys.publicKey);
+            expect(result.valid).toBe(true);
+        });
+        it("works with undefined versionTag", () => {
+            const pv = makePV({ versionTag: undefined });
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, keys.publicKey);
+            expect(result.valid).toBe(true);
+        });
+    });
+    describe("verification fails on tampered fields", () => {
+        const pv = makePV();
+        let signature;
+        beforeAll(() => {
+            signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+        });
+        it("fails when packageBundleFileHash is changed", () => {
+            const tampered = {
+                ...pv,
+                packageBundleFileHash: "tampered",
+                packageAuthorSignature: signature,
+            };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("fails when version is changed", () => {
+            const tampered = { ...pv, version: "9.9.9", packageAuthorSignature: signature };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("fails when versionTag is changed", () => {
+            const tampered = { ...pv, versionTag: "beta", packageAuthorSignature: signature };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("fails when packageId is changed", () => {
+            const tampered = { ...pv, packageId: (0, utils_1.newid)(), packageAuthorSignature: signature };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("fails when packageVersionId is changed", () => {
+            const tampered = { ...pv, packageVersionId: (0, utils_1.newid)(), packageAuthorSignature: signature };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("fails when routesBundleFileHash is changed", () => {
+            const tampered = {
+                ...pv,
+                routesBundleFileHash: "tampered",
+                packageAuthorSignature: signature,
+            };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("fails when uiBundleFileHash is changed", () => {
+            const tampered = { ...pv, uiBundleFileHash: "tampered", packageAuthorSignature: signature };
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)(tampered, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+    });
+    describe("verification fails with wrong key", () => {
+        it("rejects when verified against a different key", () => {
+            const pv = makePV();
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const otherKeys = (0, keys_1.newKeys)();
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, otherKeys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+    });
+    describe("TOFU enforcement via expectedPublicKey", () => {
+        it("succeeds when expectedPublicKey matches the signer", () => {
+            const pv = makePV();
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, keys.publicKey);
+            expect(result.valid).toBe(true);
+            expect(result.publicKey).toBe(keys.publicKey);
+        });
+        it("fails when expectedPublicKey does not match the signer", () => {
+            const pv = makePV();
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const differentKey = (0, keys_1.newKeys)().publicKey;
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, differentKey);
+            expect(result.valid).toBe(false);
+        });
+    });
+    describe("edge cases", () => {
+        it("returns invalid when packageAuthorSignature is undefined", () => {
+            const pv = makePV();
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: undefined }, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("returns invalid when packageAuthorSignature is malformed", () => {
+            const pv = makePV();
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: "not-a-valid-signature!!!" }, keys.publicKey);
+            expect(result.valid).toBe(false);
+        });
+        it("returns invalid when expectedPublicKey is malformed", () => {
+            const pv = makePV();
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, "not-a-valid-key");
+            expect(result.valid).toBe(false);
+        });
+        it("signature is deterministic for same inputs", () => {
+            const pv = makePV();
+            const sig1 = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const sig2 = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            expect(sig1).toBe(sig2);
+        });
+        it("derives the correct public key from the secret key", () => {
+            const pv = makePV();
+            const signature = (0, package_author_signing_1.signPackageAuthor)(pv, keys.secretKey);
+            const derived = (0, keys_1.hydrateKeys)(keys.secretKey);
+            expect(derived.publicKey).toBe(keys.publicKey);
+            const result = (0, package_author_signing_1.verifyPackageAuthorSignature)({ ...pv, packageAuthorSignature: signature }, derived.publicKey);
+            expect(result.valid).toBe(true);
+        });
+    });
+});

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

@@ -0,0 +1,16 @@
+import type { DataContext } from "../context/data-context";
+import type { IClonePackageOpts, IClonePackageResult, IPackageInstallerDeps } from "./types";
+/**
+ * Derive a filesystem-safe slug from a git remote URL.
+ * "https://github.com/peers-app/groceries.git" → "groceries"
+ */
+export declare function deriveRepoSlug(url: string): string;
+/**
+ * Clone a remote git repository containing a Peers package, install dependencies,
+ * build it, and register the dev bundle in the database.
+ *
+ * Prerequisites (git, npm) are validated up front with clear error messages.
+ * If the target directory already exists and contains a valid package, delegates
+ * to {@link installPackageFromBundles} instead of re-cloning.
+ */
+export declare function clonePackage(dataContext: DataContext, deps: IPackageInstallerDeps, opts: IClonePackageOpts): Promise<IClonePackageResult>;

package/dist/package-installer/package-cloner.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveRepoSlug = deriveRepoSlug;
+exports.clonePackage = clonePackage;
+const packages_1 = require("../data/packages");
+const persistent_vars_1 = require("../data/persistent-vars");
+const system_ids_1 = require("../system-ids");
+const utils_1 = require("../utils");
+const package_installer_1 = require("./package-installer");
+/**
+ * Derive a filesystem-safe slug from a git remote URL.
+ * "https://github.com/peers-app/groceries.git" → "groceries"
+ */
+function deriveRepoSlug(url) {
+    const lastSegment = url.split("/").pop() ?? "";
+    return lastSegment.replace(/\.git$/, "");
+}
+/**
+ * Determine whether a package from this remote should start disabled.
+ * Packages from the peers-app org are trusted and enabled by default.
+ */
+function autoDetectDisabled(remoteRepo) {
+    return !remoteRepo.toLowerCase().startsWith("https://github.com/peers-app/");
+}
+/**
+ * Clone a remote git repository containing a Peers package, install dependencies,
+ * build it, and register the dev bundle in the database.
+ *
+ * Prerequisites (git, npm) are validated up front with clear error messages.
+ * If the target directory already exists and contains a valid package, delegates
+ * to {@link installPackageFromBundles} instead of re-cloning.
+ */
+async function clonePackage(dataContext, deps, opts) {
+    // 1. Validate prerequisites
+    try {
+        await deps.shell.exec("git --version");
+    }
+    catch {
+        throw new Error("git is not installed. Please install git to add remote packages.");
+    }
+    try {
+        await deps.shell.exec("npm --version");
+    }
+    catch {
+        throw new Error("npm is not installed. Please install Node.js (which includes npm) to add remote packages.");
+    }
+    // 2. Resolve location
+    const location = opts.location ?? deps.resolvePath(deps.packagesRootDir, deriveRepoSlug(opts.remoteRepo));
+    // 3. Check if directory already exists
+    if (await deps.fs.exists(location)) {
+        const info = await (0, package_installer_1.getPackageInfo)(deps, location);
+        if (info.packageId && (0, utils_1.isid)(info.packageId)) {
+            const result = await (0, package_installer_1.installPackageFromBundles)(dataContext, deps, info.packageId, {
+                localPath: location,
+            });
+            return {
+                packageId: info.packageId,
+                localPath: location,
+                remoteRepo: opts.remoteRepo,
+                packageVersion: result.packageVersion,
+            };
+        }
+        throw new Error(`Directory already exists at ${location} but does not contain a valid Peers package (missing peers.packageId)`);
+    }
+    // 4. Clone
+    await deps.shell.exec(`git clone ${opts.remoteRepo} ${location}`);
+    // 5. Install + build (unless skipBuild)
+    if (!opts.skipBuild) {
+        await deps.shell.exec("npm install", { cwd: location });
+        await deps.shell.exec("npm run build", { cwd: location });
+    }
+    // 6. Read package info and resolve packageId
+    const info = await (0, package_installer_1.getPackageInfo)(deps, location);
+    let packageId;
+    if (info.packageId && (0, utils_1.isid)(info.packageId)) {
+        packageId = info.packageId;
+    }
+    else {
+        // No valid packageId in package.json — generate one and patch it in
+        packageId = (0, utils_1.newid)();
+        const packageJsonPath = deps.resolvePath(location, "package.json");
+        const packageObj = await deps.fs.readJson(packageJsonPath);
+        packageObj.peers = packageObj.peers || {};
+        packageObj.peers.packageId = packageId;
+        await deps.fs.writeFile(packageJsonPath, JSON.stringify(packageObj, null, 2));
+    }
+    // 7. Register package record
+    const disabled = opts.disabled ?? autoDetectDisabled(opts.remoteRepo);
+    await (0, packages_1.Packages)(dataContext).signAndSave({
+        packageId,
+        name: info.name,
+        description: info.description ?? "",
+        createdBy: system_ids_1.peersRootUserId,
+        disabled,
+        remoteRepo: opts.remoteRepo,
+        publishPublicKey: "",
+        signature: "",
+    }, { restoreIfDeleted: true, saveAsSnapshot: true });
+    // Set the packageLocalPath device var
+    const pvar = (0, persistent_vars_1.groupDeviceVar)(`packageLocalPath_${packageId}`, {
+        defaultValue: deps.packagesRootDir,
+        dataContext,
+    });
+    pvar(location);
+    // 8. Install dev bundle
+    const result = await (0, package_installer_1.installPackageFromBundles)(dataContext, deps, packageId, {
+        localPath: location,
+    });
+    return {
+        packageId,
+        localPath: location,
+        remoteRepo: opts.remoteRepo,
+        packageVersion: result.packageVersion,
+    };
+}

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

@@ -0,0 +1 @@
+export {};