@norskvideo/ctl-sdk 0.1.6 → 0.1.7

package/index.d.ts

@@ -5,6 +5,7 @@ export * from "./dev-url.js";
 export * from "./docker-runner.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
+export * from "./license-staged.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
 export * from "./manifest-fetch.js";

package/index.js

@@ -7,6 +7,7 @@ export * from "./dev-url.js";
 export * from "./docker-runner.js";
 export * from "./http-proxy.js";
 export * from "./license-registration.js";
+export * from "./license-staged.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
 export * from "./manifest-fetch.js";

package/license-staged.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The staged copy corresponding to an operator-supplied licence path, if one
+ * exists under `licensesDir`. `exists` is injected so this stays unit-testable.
+ */
+export declare function stagedLicenseCandidate(operatorPath: string, licensesDir: string | undefined, exists?: (path: string) => boolean): string | undefined;
+/**
+ * Explain an unreadable licence in terms of the thing that's actually wrong.
+ *
+ * A permissions failure and a missing file are different mistakes: the first is
+ * "right file, wrong path for this process", the second is a typo. Naming the
+ * daemon user on an ENOENT would send the operator hunting a permissions
+ * problem that isn't there.
+ */
+export declare function unreadableLicenseMessage(opts: {
+    operatorPath: string;
+    cause: string;
+    daemonUser: string;
+    licensesDir?: string;
+    stagedCandidate?: string;
+}): string;

package/license-staged.js

@@ -0,0 +1,55 @@
+/**
+ * Diagnostics for a licence file the daemon cannot read.
+ *
+ * The licence-driven routes (`preview-license`, `from-license`) read the file
+ * daemon-side, and the daemon runs unprivileged as its service user — so an
+ * operator who passes the path they used at install time (`~/licence.json`, in
+ * *their* home) gets an EACCES that reads like a broken licence rather than a
+ * wrong path.
+ *
+ * The remedy is almost always sitting in `licensesDir`: the installers stage a
+ * copy there, deliberately keeping the operator's basename, so the file they
+ * meant can be found by name and named back to them. Shared by the hosts (ctl
+ * and mgr) so the two daemons explain the same mistake the same way.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/**
+ * The staged copy corresponding to an operator-supplied licence path, if one
+ * exists under `licensesDir`. `exists` is injected so this stays unit-testable.
+ */
+export function stagedLicenseCandidate(operatorPath, licensesDir, exists = existsSync) {
+    if (!licensesDir)
+        return undefined;
+    // Already the staged copy — suggesting it back would be circular.
+    if (resolve(dirname(operatorPath)) === resolve(licensesDir))
+        return undefined;
+    const candidate = join(licensesDir, basename(operatorPath));
+    return exists(candidate) ? candidate : undefined;
+}
+/**
+ * Explain an unreadable licence in terms of the thing that's actually wrong.
+ *
+ * A permissions failure and a missing file are different mistakes: the first is
+ * "right file, wrong path for this process", the second is a typo. Naming the
+ * daemon user on an ENOENT would send the operator hunting a permissions
+ * problem that isn't there.
+ */
+export function unreadableLicenseMessage(opts) {
+    const { operatorPath, cause, daemonUser, licensesDir, stagedCandidate } = opts;
+    const missing = /ENOENT/.test(cause);
+    const parts = [`cannot read license file '${operatorPath}': ${cause}`];
+    if (missing) {
+        parts.push("Check the path — nothing exists there.");
+    }
+    else {
+        parts.push(`The daemon runs as '${daemonUser}', which cannot read it.`);
+    }
+    if (stagedCandidate) {
+        parts.push(`A staged licence of the same name exists at '${stagedCandidate}' — pass that instead.`);
+    }
+    else if (!missing) {
+        parts.push(`Licences are staged under ${licensesDir ?? "the daemon's licenses directory"} at install time; pass the staged path, or copy the file there readable by '${daemonUser}'.`);
+    }
+    return parts.join(" ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "exports": {
     ".": {