@peers-app/peers-sdk 0.23.8 → 0.23.9

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

@@ -1,17 +1,29 @@
 import type { DataContext } from "../context/data-context";
-import type { ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps } from "./types";
+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;
 /**
  * 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;
+/**
+ * Classify a failed `git pull` of the template cache as a network outage versus
+ * a local/git problem (dirty tree, auth, merge conflict).
+ */
+export declare function classifyTemplatePullFailure(error: unknown): TemplateCacheRefreshFailure;
 /**
  * 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.
+ * On later calls, attempts `git pull`. A failed pull does not block create;
+ * the existing cache is used and a warning is returned so the host can show it.
+ * @returns Cache path and an optional stale-template warning.
  */
-export declare function ensureTemplateCache(deps: IPackageInstallerDeps, templateRepo: string): Promise<string>;
+export declare function ensureTemplateCache(deps: IPackageInstallerDeps, templateRepo: string): Promise<ITemplateCacheResult>;
 /**
  * Resolve (or create) the Ed25519 publish public key for a package.
  *

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapAddOrUpdatePackageResult = unwrapAddOrUpdatePackageResult;
 exports.nameToFolderSlug = nameToFolderSlug;
+exports.classifyTemplatePullFailure = classifyTemplatePullFailure;
 exports.ensureTemplateCache = ensureTemplateCache;
 exports.ensurePackageSigningKey = ensurePackageSigningKey;
 exports.importExistingPackage = importExistingPackage;
@@ -22,6 +24,17 @@ 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"
@@ -31,26 +44,67 @@ function nameToFolderSlug(name) {
     slug = slug.replace(/\s+/g, " ").trim();
     return (0, utils_1.camelCaseToHyphens)(slug);
 }
+const OFFLINE_PULL_PATTERN = /unable to access|could not resolve host|failed to connect|connection (refused|timed out|reset)|network is unreachable|enotfound|etimedout|eai_again|offline|ssl connect error|could not fetch/i;
+/**
+ * Classify a failed `git pull` of the template cache as a network outage versus
+ * a local/git problem (dirty tree, auth, merge conflict).
+ */
+function classifyTemplatePullFailure(error) {
+    const text = execErrorText(error);
+    return OFFLINE_PULL_PATTERN.test(text) ? "offline" : "could-not-refresh";
+}
+function execErrorText(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const extra = "stderr" in error && typeof error.stderr === "string" ? error.stderr : "";
+    return [error.message, extra].filter(Boolean).join("\n");
+}
+function firstUsefulErrorLine(text) {
+    const line = text
+        .split(/\r?\n/)
+        .map((entry) => entry.trim())
+        .find((entry) => entry.length > 0);
+    if (!line) {
+        return "";
+    }
+    return line.length > 240 ? `${line.slice(0, 237)}...` : line;
+}
+function templateCacheWarning(failure, error) {
+    const detail = firstUsefulErrorLine(execErrorText(error));
+    const detailSuffix = detail ? ` ${detail}` : "";
+    if (failure === "offline") {
+        return ("This package was created from a cached template because the template repository could not be reached (offline or network error). It may not match the latest isolate package scaffold." +
+            detailSuffix);
+    }
+    return ("This package was created from a cached template because git pull could not update ~/peers/packages/.peers-package-template. It may be a stale version. Local changes in that cache directory are the usual cause." +
+        detailSuffix);
+}
 /**
  * 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.
+ * On later calls, attempts `git pull`. A failed pull does not block create;
+ * the existing cache is used and a warning is returned so the host can show it.
+ * @returns Cache path and an optional stale-template warning.
  */
 async function ensureTemplateCache(deps, templateRepo) {
     const cachePath = deps.resolvePath(deps.packagesRootDir, TEMPLATE_CACHE_DIR);
     if (await deps.fs.exists(cachePath)) {
         try {
             await deps.shell.exec("git pull", { cwd: cachePath });
+            return { cachePath };
         }
-        catch {
-            // Offline or remote unreachable — continue with stale cache
+        catch (error) {
+            const refreshFailure = classifyTemplatePullFailure(error);
+            return {
+                cachePath,
+                refreshFailure,
+                warning: templateCacheWarning(refreshFailure, error),
+            };
         }
     }
-    else {
-        await deps.shell.exec(`git clone ${templateRepo} ${cachePath}`);
-    }
-    return cachePath;
+    await deps.shell.exec(`git clone ${templateRepo} ${cachePath}`);
+    return { cachePath };
 }
 /**
  * Resolve (or create) the Ed25519 publish public key for a package.
@@ -202,6 +256,7 @@ async function createPackage(dataContext, deps, opts) {
     const contractId = (0, utils_1.newid)();
     const appScreenId = (0, utils_1.newid)();
     const templateRepo = opts.templateRepo ?? DEFAULT_TEMPLATE_REPO;
+    let templateWarning;
     // Get template contents into location
     if (opts.templateRepo && opts.templateRepo !== DEFAULT_TEMPLATE_REPO) {
         // Custom template — clone directly (no caching)
@@ -209,8 +264,9 @@ async function createPackage(dataContext, deps, opts) {
     }
     else {
         // Default template — use local cache for speed and offline support
-        const cachePath = await ensureTemplateCache(deps, templateRepo);
-        await deps.shell.exec(`cp -r ${cachePath}/. ${location}`);
+        const templateCache = await ensureTemplateCache(deps, templateRepo);
+        templateWarning = templateCache.warning;
+        await deps.shell.exec(`cp -r ${templateCache.cachePath}/. ${location}`);
     }
     // Patch package.json
     const packageJsonPath = deps.resolvePath(location, "package.json");
@@ -273,5 +329,6 @@ async function createPackage(dataContext, deps, opts) {
         packageId,
         localPath: location,
         packageVersion: result.packageVersion,
+        templateWarning,
     };
 }

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

@@ -83,6 +83,22 @@ beforeEach(() => {
         publicBoxKey: "test-box-key",
     });
 });
+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");
@@ -201,6 +217,37 @@ describe("createPackage", () => {
         });
         expect(result.localPath).toBe("/packages/my-widget");
         expect(result.packageVersion).toBe(mockPv);
+        expect(result.templateWarning).toBeUndefined();
+    });
+    it("returns a stale-template warning when the cached template cannot be refreshed", async () => {
+        const shellExec = jest.fn(async (cmd) => {
+            if (cmd === "git pull") {
+                throw new Error("error: Your local changes to the following files would be overwritten by merge:\n\t.gitignore");
+            }
+            return { stdout: "", stderr: "" };
+        });
+        const deps = makeMockDeps({}, shellExec);
+        const dc = mockDataContext();
+        deps.fs.exists.mockImplementation(async (path) => {
+            if (path === "/packages/desk")
+                return false;
+            if (path === "/packages/.peers-package-template")
+                return true;
+            return false;
+        });
+        deps.fs.readJson.mockResolvedValue({ name: "template", peers: {} });
+        const pvarSetter = jest.fn();
+        mockGroupDeviceVar.mockReturnValue(pvarSetter);
+        mockInstallPackageFromBundles.mockResolvedValue({
+            packageVersion: { packageVersionId: "pv" },
+            loaded: undefined,
+            unchanged: false,
+        });
+        const result = await (0, package_creator_1.createPackage)(dc, deps, { name: "Desk" });
+        expect(result.templateWarning).toMatch(/stale version/i);
+        expect(result.templateWarning).toMatch(/local changes/i);
+        expect(result.localPath).toBe("/packages/desk");
+        expect(deps.shell.exec).toHaveBeenCalledWith("cp -r /packages/.peers-package-template/. /packages/desk");
     });
     it("registers metadata, path, and signing key when importing an existing package directory", async () => {
         const deps = makeMockDeps({});
@@ -447,14 +494,16 @@ describe("ensureTemplateCache", () => {
         const deps = makeMockDeps({});
         deps.fs.exists.mockResolvedValue(false);
         const result = await (0, package_creator_1.ensureTemplateCache)(deps, "https://github.com/peers-app/peers-package-template.git");
-        expect(result).toBe("/packages/.peers-package-template");
+        expect(result.cachePath).toBe("/packages/.peers-package-template");
+        expect(result.warning).toBeUndefined();
         expect(deps.shell.exec).toHaveBeenCalledWith("git clone https://github.com/peers-app/peers-package-template.git /packages/.peers-package-template");
     });
     it("pulls latest when cache directory already exists", async () => {
         const deps = makeMockDeps({});
         deps.fs.exists.mockResolvedValue(true);
         const result = await (0, package_creator_1.ensureTemplateCache)(deps, "https://github.com/peers-app/peers-package-template.git");
-        expect(result).toBe("/packages/.peers-package-template");
+        expect(result.cachePath).toBe("/packages/.peers-package-template");
+        expect(result.warning).toBeUndefined();
         expect(deps.shell.exec).toHaveBeenCalledWith("git pull", {
             cwd: "/packages/.peers-package-template",
         });
@@ -462,16 +511,43 @@ describe("ensureTemplateCache", () => {
         const execCalls = deps.shell.exec.mock.calls.map((c) => c[0]);
         expect(execCalls).not.toContain(expect.stringContaining("git clone"));
     });
-    it("continues silently when pull fails (offline)", async () => {
+    it("returns an offline warning when pull cannot reach the remote", async () => {
+        const shellExec = jest.fn(async (cmd) => {
+            if (cmd === "git pull") {
+                throw new Error("fatal: unable to access 'https://github.com/peers-app/peers-package-template.git'");
+            }
+            return { stdout: "", stderr: "" };
+        });
+        const deps = makeMockDeps({}, shellExec);
+        deps.fs.exists.mockResolvedValue(true);
+        const result = await (0, package_creator_1.ensureTemplateCache)(deps, "https://github.com/peers-app/peers-package-template.git");
+        expect(result.cachePath).toBe("/packages/.peers-package-template");
+        expect(result.refreshFailure).toBe("offline");
+        expect(result.warning).toMatch(/could not be reached/i);
+    });
+    it("returns a could-not-refresh warning when pull fails for local git reasons", async () => {
         const shellExec = jest.fn(async (cmd) => {
-            if (cmd === "git pull")
-                throw new Error("fatal: unable to access remote");
+            if (cmd === "git pull") {
+                throw new Error("error: Your local changes to the following files would be overwritten by merge:\n\t.gitignore");
+            }
             return { stdout: "", stderr: "" };
         });
         const deps = makeMockDeps({}, shellExec);
         deps.fs.exists.mockResolvedValue(true);
         const result = await (0, package_creator_1.ensureTemplateCache)(deps, "https://github.com/peers-app/peers-package-template.git");
-        // Should not throw, returns cache path
-        expect(result).toBe("/packages/.peers-package-template");
+        expect(result.cachePath).toBe("/packages/.peers-package-template");
+        expect(result.refreshFailure).toBe("could-not-refresh");
+        expect(result.warning).toMatch(/stale version/i);
+        expect(result.warning).toMatch(/overwritten by merge/i);
+    });
+});
+describe("classifyTemplatePullFailure", () => {
+    it("treats unreachable remotes as offline", () => {
+        expect((0, package_creator_1.classifyTemplatePullFailure)(new Error("fatal: unable to access remote"))).toBe("offline");
+        expect((0, package_creator_1.classifyTemplatePullFailure)(new Error("Could not resolve host: github.com"))).toBe("offline");
+    });
+    it("treats dirty trees and auth problems as could-not-refresh", () => {
+        expect((0, package_creator_1.classifyTemplatePullFailure)(new Error("Your local changes to the following files would be overwritten by merge"))).toBe("could-not-refresh");
+        expect((0, package_creator_1.classifyTemplatePullFailure)(new Error("Permission denied (publickey)"))).toBe("could-not-refresh");
     });
 });

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

@@ -84,11 +84,40 @@ export interface ICreatePackageOpts {
      */
     personalContext?: import("../context/data-context").DataContext;
 }
+/** Why a `git pull` of the cached package template did not succeed. */
+export type TemplateCacheRefreshFailure = "offline" | "could-not-refresh";
+/** Local template cache path plus a non-fatal refresh warning when present. */
+export interface ITemplateCacheResult {
+    /** Directory copied from when scaffolding a new package. */
+    cachePath: string;
+    /** Set when `git pull` failed and the existing cache was used anyway. */
+    refreshFailure?: TemplateCacheRefreshFailure;
+    /** User-facing explanation when {@link refreshFailure} is set. */
+    warning?: string;
+}
 /** Result of {@link createPackage}. */
 export interface ICreatePackageResult {
+    /** New or imported package ID. */
     packageId: string;
+    /** On-disk package directory. */
     localPath: string;
+    /** Installed local/dev package version record. */
     packageVersion: IPackageVersion;
+    /**
+     * Present when the default template cache could not be refreshed and a
+     * possibly stale copy was used. Creation still succeeded.
+     */
+    templateWarning?: string;
+}
+/** Host/RPC result for adding, creating, or updating a package. */
+export interface IAddOrUpdatePackageResult {
+    /** Package that was created, imported, cloned, or updated. */
+    packageId: string;
+    /**
+     * Non-fatal notice after a successful local create (for example a stale
+     * template cache). Undefined on update, clone, and import of an existing directory.
+     */
+    warning?: string;
 }
 /** Options for {@link clonePackage}. */
 export interface IClonePackageOpts {
@@ -103,8 +132,12 @@ export interface IClonePackageOpts {
 }
 /** Result of {@link clonePackage}. */
 export interface IClonePackageResult {
+    /** Imported package ID from the cloned repo. */
     packageId: string;
+    /** On-disk clone directory. */
     localPath: string;
+    /** Git URL that was cloned. */
     remoteRepo: string;
+    /** Installed local/dev package version record. */
     packageVersion: IPackageVersion;
 }

package/dist/rpc-types.d.ts

@@ -2,6 +2,7 @@ import type { IDeviceDatabaseQueryResult, IDeviceOperationStatus, IDeviceToolRun
 import type { ITool } from "./data/tools";
 import type { DevicePairingCeremonyAction, DevicePairingStartDestinationInput, DevicePairingStartSourceResult, DevicePairingState } from "./device-pairing";
 import type { IConsoleLog } from "./logging/console-logs.table";
+import type { IAddOrUpdatePackageResult } from "./package-installer/types";
 import type { IAppNav } from "./types/app-nav";
 /** Named event payload sent across the frontend RPC bridge. */
 export interface IEventData<T = any> {
@@ -61,7 +62,7 @@ export declare const rpcServerCalls: {
         packageLocation?: string;
         update?: boolean;
         linkRemote?: boolean;
-    }) => Promise<string>;
+    }) => Promise<string | IAddOrUpdatePackageResult>;
     seedBundledPeersCore: (dataContextId?: string) => Promise<boolean>;
     setUserIdAndSecretKey: (userId: string, secretKey: string) => Promise<void>;
     getUserId: () => Promise<string | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.23.8",
+  "version": "0.23.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"