@relayflows/sdk 2.0.24 → 2.0.26

package/src/plugin-store.ts

@@ -0,0 +1,105 @@
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { payloadManifest, safePath, sha256 } from './bundle.js';
+import { PluginError } from './plugin-manifest.js';
+
+/**
+ * Where a flow-extension plugin's bytes live inside a project:
+ * `<project>/.flows/plugins/<name>@sha256:<digest>/`, content-addressed like
+ * the bundle cache and never `node_modules`. `manifest.json` in that directory
+ * is the payload manifest whose sha256 is the digest, so a directory can be
+ * re-verified without the network — and, because the lockfile records the
+ * same digest, drift between what was installed and what is on disk is a
+ * refusal, not a surprise.
+ */
+export const PLUGIN_STORE = '.flows/plugins';
+
+export function pluginStoreDirectory(root: string, name: string, digest: string): string {
+  return join(resolve(root), PLUGIN_STORE, `${name}@sha256:${digest}`);
+}
+
+export interface StoredPluginFile { readonly path: string; readonly data: Uint8Array }
+
+/** Write the files atomically; an existing directory is verified instead of overwritten. */
+export async function materializePlugin(root: string, name: string, files: readonly StoredPluginFile[]): Promise<{ directory: string; digest: string }> {
+  const manifest = payloadManifest(files);
+  const digest = sha256(manifest);
+  const directory = pluginStoreDirectory(root, name, digest);
+  let exists = false;
+  try { await lstat(directory); exists = true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  if (exists) { await verifyStoredPlugin(directory, digest); return { directory, digest }; }
+  const parent = dirname(directory);
+  await mkdir(parent, { recursive: true });
+  const staging = await mkdtemp(join(parent, '.install-'));
+  try {
+    for (const file of files) {
+      if (!safePath(file.path) || file.path === 'manifest.json') throw new PluginError('plugin_path_invalid', `${file.path}: invalid plugin path.`);
+      await mkdir(dirname(join(staging, file.path)), { recursive: true });
+      await writeFile(join(staging, file.path), file.data, { mode: 0o644 });
+    }
+    await writeFile(join(staging, 'manifest.json'), manifest);
+    try { await rename(staging, directory); }
+    catch (error) {
+      if (!['EEXIST', 'ENOTEMPTY'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      await verifyStoredPlugin(directory, digest);
+    }
+  } finally { await rm(staging, { recursive: true, force: true }); }
+  return { directory, digest };
+}
+
+async function regularFile(root: string, path: string): Promise<Buffer> {
+  const parts = path.split('/');
+  for (let i = 1; i <= parts.length; i++) {
+    const stat = await lstat(join(root, ...parts.slice(0, i)));
+    if (i === parts.length ? !stat.isFile() : !stat.isDirectory()) throw new PluginError('plugin_source_drift', `${path}: expected a regular file, without symlinks.`);
+  }
+  return readFile(join(root, path));
+}
+
+/** Re-hash a materialized plugin and compare with the digest the lockfile recorded. */
+export async function verifyStoredPlugin(directory: string, expectedDigest: string): Promise<void> {
+  const drift = (message: string): never => { throw new PluginError('plugin_source_drift', `${directory}: ${message}`); };
+  let raw: string;
+  try {
+    if (!(await lstat(directory)).isDirectory()) return drift('not a directory');
+    raw = (await regularFile(directory, 'manifest.json')).toString('utf8');
+  } catch (error) { return drift(error instanceof PluginError ? error.message : 'manifest.json is missing'); }
+  if (sha256(raw) !== expectedDigest) return drift('manifest.json digest differs from the lockfile');
+  let entries: { path: string; sha256: string; bytes: number }[];
+  try { entries = JSON.parse(raw); if (!Array.isArray(entries)) throw new Error(); }
+  catch { return drift('manifest.json is not a manifest'); }
+  const paths = new Set<string>();
+  for (const entry of entries) {
+    if (typeof entry?.path !== 'string' || !safePath(entry.path)) return drift('manifest.json lists an invalid path');
+    let data: Buffer;
+    try { data = await regularFile(directory, entry.path); }
+    catch (error) { return drift(error instanceof PluginError ? error.message : `${entry.path} is missing`); }
+    if (data.length !== entry.bytes || sha256(data) !== entry.sha256) return drift(`${entry.path} changed since installation`);
+    paths.add(entry.path);
+  }
+  await rejectExtras(directory, '', new Set([...paths, 'manifest.json']), drift);
+}
+
+/** Re-verify, then return every stored file including the payload `manifest.json`. */
+export async function readStoredPluginFiles(directory: string, expectedDigest: string): Promise<readonly { path: string; data: Buffer }[]> {
+  await verifyStoredPlugin(directory, expectedDigest);
+  const manifest = await regularFile(directory, 'manifest.json');
+  const entries = JSON.parse(manifest.toString('utf8')) as { path: string }[];
+  const files = [{ path: 'manifest.json', data: manifest }];
+  for (const entry of entries) files.push({ path: entry.path, data: await regularFile(directory, entry.path) });
+  return files;
+}
+
+/** Drop a materialized plugin directory. Missing is a no-op. */
+export async function removeStoredPlugin(directory: string): Promise<void> {
+  await rm(directory, { recursive: true, force: true });
+}
+
+async function rejectExtras(root: string, prefix: string, paths: Set<string>, drift: (m: string) => never): Promise<void> {
+  for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+    const path = prefix + entry.name;
+    if (entry.isDirectory() && [...paths].some(file => file.startsWith(`${path}/`))) await rejectExtras(root, `${path}/`, paths, drift);
+    else if (!entry.isFile() || !paths.has(path)) drift(`${path}: unlisted file or unsupported file type`);
+  }
+}

package/src/semver-range.ts

@@ -0,0 +1,74 @@
+/**
+ * The small semver subset plugin `compat` ranges may use. Deliberately not a
+ * dependency on `semver`: a plugin's compatibility claim has to be checkable by
+ * every reader — Cloud, the CLI, a catalog — from one short, obvious rule.
+ *
+ * Accepted: `*`, `x.y.z`, `^x.y.z`, `~x.y.z`, `>=x.y.z`, `>=x.y.z <a.b.c`.
+ * Prerelease tags are ordered lexically after the numeric triple and only
+ * compare against a range whose bounds name the same triple.
+ */
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+const RANGE = /^(\*|(?:[\^~]|>=)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?: <\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)?)$/;
+
+interface Parsed { readonly triple: readonly [number, number, number]; readonly pre?: string }
+
+export function parseVersion(value: string): Parsed | undefined {
+  const m = VERSION.exec(value);
+  if (!m) return undefined;
+  const triple = [Number(m[1]), Number(m[2]), Number(m[3])] as const;
+  if (triple.some(n => !Number.isSafeInteger(n))) return undefined;
+  return m[4] === undefined ? { triple } : { triple, pre: m[4] };
+}
+
+export function isVersionRange(value: string): boolean {
+  return RANGE.test(value);
+}
+
+function compare(a: Parsed, b: Parsed): number {
+  for (let i = 0; i < 3; i++) if (a.triple[i] !== b.triple[i]) return a.triple[i]! - b.triple[i]!;
+  if (a.pre === b.pre) return 0;
+  if (a.pre === undefined) return 1;
+  if (b.pre === undefined) return -1;
+  return comparePrerelease(a.pre, b.pre);
+}
+
+function comparePrerelease(a: string, b: string): number {
+  const as = a.split('.');
+  const bs = b.split('.');
+  const n = Math.max(as.length, bs.length);
+  for (let i = 0; i < n; i++) {
+    const left = as[i];
+    const right = bs[i];
+    if (left === undefined) return -1;
+    if (right === undefined) return 1;
+    const leftNum = /^\d+$/.test(left) ? Number(left) : undefined;
+    const rightNum = /^\d+$/.test(right) ? Number(right) : undefined;
+    if (leftNum !== undefined && rightNum !== undefined) {
+      if (leftNum !== rightNum) return leftNum - rightNum;
+      continue;
+    }
+    if (leftNum !== undefined) return -1;
+    if (rightNum !== undefined) return 1;
+    if (left !== right) return left < right ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Whether `version` satisfies `range`; false for malformed input rather than a throw. */
+export function satisfiesRange(version: string, range: string): boolean {
+  const v = parseVersion(version);
+  if (v === undefined || !isVersionRange(range)) return false;
+  if (range === '*') return true;
+  const [lowerText, upperText] = range.split(' ') as [string, string | undefined];
+  const operator = /^[\^~]|^>=/.exec(lowerText)?.[0] ?? '';
+  const lower = parseVersion(lowerText.slice(operator.length))!;
+  if (compare(v, lower) < 0) return false;
+  if (operator === '') return compare(v, lower) === 0;
+  let upper: Parsed | undefined;
+  if (upperText !== undefined) upper = parseVersion(upperText.slice(1));
+  else if (operator === '^') {
+    const [major, minor] = lower.triple;
+    upper = major > 0 ? { triple: [major + 1, 0, 0] } : minor > 0 ? { triple: [0, minor + 1, 0] } : { triple: [0, 0, lower.triple[2] + 1] };
+  } else if (operator === '~') upper = { triple: [lower.triple[0], lower.triple[1] + 1, 0] };
+  return upper === undefined || compare(v, upper) < 0;
+}