@peers-app/peers-sdk 0.18.6 → 0.19.0

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 {};

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

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const package_cloner_1 = require("./package-cloner");
+// --- Mocks for SDK internals ---
+const mockSignAndSavePkg = jest.fn();
+jest.mock("../data/packages", () => ({
+    Packages: () => ({
+        signAndSave: mockSignAndSavePkg,
+    }),
+}));
+const mockGroupDeviceVar = jest.fn();
+jest.mock("../data/persistent-vars", () => ({
+    groupDeviceVar: (...args) => mockGroupDeviceVar(...args),
+}));
+const mockInstallPackageFromBundles = jest.fn();
+const mockGetPackageInfo = jest.fn();
+jest.mock("./package-installer", () => ({
+    installPackageFromBundles: (...args) => mockInstallPackageFromBundles(...args),
+    getPackageInfo: (...args) => mockGetPackageInfo(...args),
+}));
+// --- Test utilities ---
+function makeMockDeps(shellExec) {
+    return {
+        fs: {
+            readFile: jest.fn(async () => ""),
+            writeFile: jest.fn(async () => { }),
+            exists: jest.fn(async () => false),
+            readJson: jest.fn(async () => ({})),
+        },
+        shell: {
+            exec: shellExec ?? jest.fn(async () => ({ stdout: "", stderr: "" })),
+        },
+        resolvePath: (...segments) => segments.join("/"),
+        packagesRootDir: "/packages",
+    };
+}
+function mockDataContext() {
+    return {
+        packageLoader: {
+            loadPackage: jest.fn().mockResolvedValue(undefined),
+        },
+    };
+}
+// --- Tests ---
+beforeEach(() => {
+    jest.clearAllMocks();
+});
+describe("deriveRepoSlug", () => {
+    it("extracts slug from https URL with .git suffix", () => {
+        expect((0, package_cloner_1.deriveRepoSlug)("https://github.com/peers-app/groceries.git")).toBe("groceries");
+    });
+    it("extracts slug from https URL without .git suffix", () => {
+        expect((0, package_cloner_1.deriveRepoSlug)("https://github.com/user/my-pkg")).toBe("my-pkg");
+    });
+    it("handles SSH-style URLs", () => {
+        expect((0, package_cloner_1.deriveRepoSlug)("git@github.com:user/some-repo.git")).toBe("some-repo");
+    });
+    it("returns empty string for empty URL", () => {
+        expect((0, package_cloner_1.deriveRepoSlug)("")).toBe("");
+    });
+});
+describe("clonePackage", () => {
+    it("throws when git is not installed", async () => {
+        const shellExec = jest.fn(async (cmd) => {
+            if (cmd === "git --version")
+                throw new Error("not found");
+            return { stdout: "", stderr: "" };
+        });
+        const deps = makeMockDeps(shellExec);
+        const dc = mockDataContext();
+        await expect((0, package_cloner_1.clonePackage)(dc, deps, { remoteRepo: "https://github.com/peers-app/test.git" })).rejects.toThrow("git is not installed");
+    });
+    it("throws when npm is not installed", async () => {
+        const shellExec = jest.fn(async (cmd) => {
+            if (cmd === "npm --version")
+                throw new Error("not found");
+            return { stdout: "", stderr: "" };
+        });
+        const deps = makeMockDeps(shellExec);
+        const dc = mockDataContext();
+        await expect((0, package_cloner_1.clonePackage)(dc, deps, { remoteRepo: "https://github.com/peers-app/test.git" })).rejects.toThrow("npm is not installed");
+    });
+    it("clones, installs, builds, and registers a package with valid packageId", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        // Directory doesn't exist
+        deps.fs.exists.mockResolvedValue(false);
+        // After clone, getPackageInfo returns a valid package
+        mockGetPackageInfo.mockResolvedValue({
+            packageId: "00mnkoyo7mizav6tseubjzr3a",
+            name: "groceries",
+            description: "Shopping list app",
+        });
+        const pvarSetter = jest.fn();
+        mockGroupDeviceVar.mockReturnValue(pvarSetter);
+        const mockPv = { packageVersionId: "pv001" };
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: mockPv,
+            loaded: undefined,
+            unchanged: false,
+        });
+        const result = await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/peers-app/groceries.git",
+        });
+        // Verify clone
+        expect(deps.shell.exec).toHaveBeenCalledWith("git clone https://github.com/peers-app/groceries.git /packages/groceries");
+        // Verify install + build
+        expect(deps.shell.exec).toHaveBeenCalledWith("npm install", { cwd: "/packages/groceries" });
+        expect(deps.shell.exec).toHaveBeenCalledWith("npm run build", { cwd: "/packages/groceries" });
+        // Verify package record was created (peers-app org = not disabled)
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+            packageId: "00mnkoyo7mizav6tseubjzr3a",
+            name: "groceries",
+            description: "Shopping list app",
+            disabled: false,
+            remoteRepo: "https://github.com/peers-app/groceries.git",
+        }), { restoreIfDeleted: true, saveAsSnapshot: true });
+        // Verify device var
+        expect(pvarSetter).toHaveBeenCalledWith("/packages/groceries");
+        // Verify install
+        expect(mockInstallPackageFromBundles).toHaveBeenCalledWith(dc, deps, "00mnkoyo7mizav6tseubjzr3a", { localPath: "/packages/groceries" });
+        expect(result.packageId).toBe("00mnkoyo7mizav6tseubjzr3a");
+        expect(result.localPath).toBe("/packages/groceries");
+        expect(result.remoteRepo).toBe("https://github.com/peers-app/groceries.git");
+        expect(result.packageVersion).toBe(mockPv);
+    });
+    it("auto-disables packages from non-peers-app orgs", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        deps.fs.exists.mockResolvedValue(false);
+        mockGetPackageInfo.mockResolvedValue({
+            packageId: "00mnkoyo7mizav6tseubjzr3b",
+            name: "external-pkg",
+        });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: { packageVersionId: "pv" },
+            loaded: undefined,
+            unchanged: false,
+        });
+        await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/some-user/external-pkg.git",
+        });
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({ disabled: true }), expect.any(Object));
+    });
+    it("respects explicit disabled override", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        deps.fs.exists.mockResolvedValue(false);
+        mockGetPackageInfo.mockResolvedValue({
+            packageId: "00mnkoyo7mizav6tseubjzr3c",
+            name: "forced-enabled",
+        });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: { packageVersionId: "pv" },
+            loaded: undefined,
+            unchanged: false,
+        });
+        // External repo but explicitly enabled
+        await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/external/pkg.git",
+            disabled: false,
+        });
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({ disabled: false }), expect.any(Object));
+    });
+    it("skips build when skipBuild is true", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        deps.fs.exists.mockResolvedValue(false);
+        mockGetPackageInfo.mockResolvedValue({
+            packageId: "00mnkoyo7mizav6tseubjzr3d",
+            name: "prebuilt",
+        });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: { packageVersionId: "pv" },
+            loaded: undefined,
+            unchanged: false,
+        });
+        await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/peers-app/prebuilt.git",
+            skipBuild: true,
+        });
+        const execCalls = deps.shell.exec.mock.calls.map((c) => c[0]);
+        expect(execCalls).toContain("git --version");
+        expect(execCalls).toContain("npm --version");
+        expect(execCalls).toContain("git clone https://github.com/peers-app/prebuilt.git /packages/prebuilt");
+        expect(execCalls).not.toContain("npm install");
+        expect(execCalls).not.toContain("npm run build");
+    });
+    it("generates packageId and patches package.json when repo has no valid ID", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        deps.fs.exists.mockResolvedValue(false);
+        // No valid packageId
+        mockGetPackageInfo.mockResolvedValue({
+            name: "no-id-package",
+            description: "A package without peers config",
+        });
+        // readJson returns a package.json without peers.packageId
+        deps.fs.readJson.mockResolvedValue({
+            name: "no-id-package",
+            version: "1.0.0",
+        });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: { packageVersionId: "pv" },
+            loaded: undefined,
+            unchanged: false,
+        });
+        const result = await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/peers-app/no-id-package.git",
+        });
+        // Should have written a patched package.json
+        expect(deps.fs.writeFile).toHaveBeenCalledWith("/packages/no-id-package/package.json", expect.any(String));
+        const patchedJson = JSON.parse(deps.fs.writeFile.mock.calls[0][1]);
+        expect(patchedJson.peers.packageId).toMatch(/^[a-z0-9]{25}$/);
+        // Result should use the generated ID
+        expect(result.packageId).toMatch(/^[a-z0-9]{25}$/);
+    });
+    it("delegates to installPackageFromBundles when directory already exists with valid package", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        // Location exists
+        deps.fs.exists.mockResolvedValue(true);
+        mockGetPackageInfo.mockResolvedValue({
+            packageId: "00mnkoyo7mizav6tseubjzr3e",
+            name: "existing",
+        });
+        const mockPv = { packageVersionId: "pvexist" };
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: mockPv,
+            loaded: undefined,
+            unchanged: true,
+        });
+        const result = await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/peers-app/existing.git",
+        });
+        // Should NOT clone or build
+        const execCalls = deps.shell.exec.mock.calls.map((c) => c[0]);
+        expect(execCalls).not.toContain(expect.stringContaining("git clone"));
+        expect(execCalls).not.toContain("npm install");
+        // Should delegate
+        expect(mockInstallPackageFromBundles).toHaveBeenCalled();
+        expect(result.packageId).toBe("00mnkoyo7mizav6tseubjzr3e");
+    });
+    it("throws when directory exists but has no valid packageId", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        deps.fs.exists.mockResolvedValue(true);
+        mockGetPackageInfo.mockResolvedValue({ name: "invalid-pkg" });
+        await expect((0, package_cloner_1.clonePackage)(dc, deps, { remoteRepo: "https://github.com/user/invalid-pkg.git" })).rejects.toThrow("does not contain a valid Peers package");
+    });
+    it("uses custom location when provided", async () => {
+        const deps = makeMockDeps();
+        const dc = mockDataContext();
+        deps.fs.exists.mockResolvedValue(false);
+        mockGetPackageInfo.mockResolvedValue({
+            packageId: "00mnkoyo7mizav6tseubjzr3f",
+            name: "custom-loc",
+        });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: { packageVersionId: "pv" },
+            loaded: undefined,
+            unchanged: false,
+        });
+        await (0, package_cloner_1.clonePackage)(dc, deps, {
+            remoteRepo: "https://github.com/peers-app/test.git",
+            location: "/custom/install/path",
+        });
+        expect(deps.shell.exec).toHaveBeenCalledWith("git clone https://github.com/peers-app/test.git /custom/install/path");
+        expect(deps.shell.exec).toHaveBeenCalledWith("npm install", { cwd: "/custom/install/path" });
+    });
+});

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

@@ -0,0 +1,22 @@
+import type { DataContext } from "../context/data-context";
+import type { ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps } from "./types";
+/**
+ * Convert a human-readable package name to a filesystem-safe folder slug.
+ * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"
+ */
+export declare function nameToFolderSlug(name: string): string;
+/**
+ * Ensure the package template is available locally.
+ * On first call, clones the template repo into a dot-prefixed cache directory.
+ * On subsequent calls, attempts a `git pull` to refresh (continues silently if offline).
+ * @returns The path to the cached template directory.
+ */
+export declare function ensureTemplateCache(deps: IPackageInstallerDeps, templateRepo: string): Promise<string>;
+/**
+ * Create a new Peers package from the package template.
+ *
+ * Clones the template repo, patches IDs and metadata, runs npm install + build,
+ * initializes a fresh git repo, then delegates to {@link installPackageFromBundles}
+ * to register the dev bundle in the database.
+ */
+export declare function createPackage(dataContext: DataContext, deps: IPackageInstallerDeps, opts: ICreatePackageOpts): Promise<ICreatePackageResult>;