@relayflows/sdk 2.0.24 → 2.0.25

package/src/plugin-github.ts

@@ -0,0 +1,98 @@
+import { payloadManifest, safePath, sha256 } from './bundle.js';
+import { PluginError } from './plugin-manifest.js';
+import { SHA, type PluginSourceInput, type PluginSourceRef } from './plugin-source.js';
+
+/**
+ * Public, unauthenticated GitHub reads for flow-extension plugins — the same
+ * posture as Cloud's deploy links: no credential ever travels to GitHub, so a
+ * private repository simply answers 404 and is reported as unresolved.
+ *
+ * Two calls resolve a ref and enumerate a tree; blobs come from
+ * raw.githubusercontent.com pinned to the resolved commit. Every byte count is
+ * checked against the tree listing, and the tree is refused if GitHub
+ * truncated it, if it contains a symlink or submodule under the plugin path,
+ * or if any file or the whole plugin exceeds the bounds below.
+ */
+export type FetchLike = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<Response>;
+
+export const MAX_PLUGIN_FILE_BYTES = 256_000;
+export const MAX_PLUGIN_TOTAL_BYTES = 2_000_000;
+export const MAX_PLUGIN_FILES = 500;
+const TIMEOUT_MS = 15_000;
+const API = 'https://api.github.com';
+const RAW = 'https://raw.githubusercontent.com';
+
+export interface FetchedPluginFile { readonly path: string; readonly data: Buffer }
+export interface FetchedPlugin {
+  readonly source: PluginSourceRef;
+  /** Plugin-relative paths, sorted. */
+  readonly files: readonly FetchedPluginFile[];
+  /** sha256 of `payloadManifest(files)`: the content identity persisted as `@sha256:`. */
+  readonly digest: string;
+}
+
+async function request(fetch: FetchLike, url: string, accept: string): Promise<Response> {
+  let response: Response;
+  try {
+    response = await fetch(url, { headers: { accept, 'user-agent': 'relayflows-sdk' }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+  } catch (error) {
+    throw new PluginError('plugin_fetch_failed', `GitHub request failed: ${url} (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  if (response.status === 404) throw new PluginError('plugin_source_unresolved', `Not found on GitHub (or not public): ${url}.`);
+  if (!response.ok) throw new PluginError('plugin_fetch_failed', `GitHub answered ${response.status} for ${url}.`);
+  return response;
+}
+
+/** Branch, tag, or commit → the commit sha it names right now; a sha input is verified to exist. */
+export async function resolveGithubSha(source: PluginSourceInput, fetch: FetchLike = globalThis.fetch): Promise<PluginSourceRef> {
+  const url = `${API}/repos/${source.owner}/${source.repo}/commits/${encodeURIComponent(source.ref)}`;
+  const sha = (await (await request(fetch, url, 'application/vnd.github.sha')).text()).trim();
+  if (!SHA.test(sha)) throw new PluginError('plugin_fetch_failed', `GitHub returned a malformed commit sha for ${source.ref}.`);
+  if (SHA.test(source.ref) && sha !== source.ref) throw new PluginError('plugin_source_unresolved', `Commit ${source.ref} resolved to ${sha}.`);
+  return Object.freeze({ ...source, sha });
+}
+
+interface TreeEntry { path: string; mode: string; type: string; size?: number }
+
+async function listTree(source: PluginSourceRef, fetch: FetchLike): Promise<TreeEntry[]> {
+  const url = `${API}/repos/${source.owner}/${source.repo}/git/trees/${source.sha}?recursive=1`;
+  let body: unknown;
+  try { body = await (await request(fetch, url, 'application/vnd.github+json')).json(); }
+  catch { throw new PluginError('plugin_fetch_failed', 'GitHub tree listing is not JSON.'); }
+  const tree = typeof body === 'object' && body !== null ? (body as { tree?: unknown; truncated?: unknown }) : {};
+  if (tree.truncated === true) throw new PluginError('plugin_fetch_failed', 'GitHub truncated the tree listing; the repository is too large to enumerate safely.');
+  if (!Array.isArray(tree.tree)) throw new PluginError('plugin_fetch_failed', 'GitHub tree listing has no entries.');
+  return tree.tree.filter((e): e is TreeEntry => typeof e === 'object' && e !== null
+    && typeof (e as TreeEntry).path === 'string' && typeof (e as TreeEntry).mode === 'string' && typeof (e as TreeEntry).type === 'string');
+}
+
+/** Enumerate and download the plugin directory at the pinned commit, bounded and verified. */
+export async function fetchGithubPlugin(source: PluginSourceRef, fetch: FetchLike = globalThis.fetch): Promise<FetchedPlugin> {
+  const prefix = source.path === '' ? '' : `${source.path}/`;
+  const entries = (await listTree(source, fetch)).filter(e => e.path.startsWith(prefix));
+  if (source.path !== '' && entries.length === 0) throw new PluginError('plugin_source_unresolved', `${source.path} does not exist at ${source.sha}.`);
+  const blobs: { path: string; size: number }[] = [];
+  let total = 0;
+  for (const entry of entries) {
+    const relative = entry.path.slice(prefix.length);
+    if (entry.type === 'tree') continue;
+    if (entry.type === 'commit') throw new PluginError('plugin_path_invalid', `${entry.path} is a submodule; plugins must be plain files.`);
+    if (entry.mode === '120000') throw new PluginError('plugin_path_invalid', `${entry.path} is a symlink; plugins must be plain files.`);
+    if (entry.type !== 'blob' || !safePath(relative)) throw new PluginError('plugin_path_invalid', `${entry.path} is not a plain repository file.`);
+    if (!Number.isSafeInteger(entry.size) || entry.size! < 0) throw new PluginError('plugin_fetch_failed', `${entry.path} has no size in the tree listing.`);
+    if (entry.size! > MAX_PLUGIN_FILE_BYTES) throw new PluginError('plugin_too_large', `${entry.path} is ${entry.size} bytes; the limit is ${MAX_PLUGIN_FILE_BYTES}.`);
+    total += entry.size!;
+    if (total > MAX_PLUGIN_TOTAL_BYTES) throw new PluginError('plugin_too_large', `Plugin exceeds ${MAX_PLUGIN_TOTAL_BYTES} bytes in total.`);
+    blobs.push({ path: relative, size: entry.size! });
+    if (blobs.length > MAX_PLUGIN_FILES) throw new PluginError('plugin_too_large', `Plugin has more than ${MAX_PLUGIN_FILES} files.`);
+  }
+  if (!blobs.some(b => b.path === 'flows-plugin.json')) throw new PluginError('plugin_manifest_missing', `${source.owner}/${source.repo}@${source.sha}${prefix === '' ? '' : `#${source.path}`} has no flows-plugin.json.`);
+  const files: FetchedPluginFile[] = [];
+  for (const blob of blobs.sort((a, b) => a.path < b.path ? -1 : 1)) {
+    const url = `${RAW}/${source.owner}/${source.repo}/${source.sha}/${prefix}${blob.path}`;
+    const data = Buffer.from(await (await request(fetch, url, 'application/octet-stream')).arrayBuffer());
+    if (data.length !== blob.size) throw new PluginError('plugin_source_drift', `${blob.path}: fetched ${data.length} bytes, tree lists ${blob.size}.`);
+    files.push(Object.freeze({ path: blob.path, data }));
+  }
+  return Object.freeze({ source, files: Object.freeze(files), digest: sha256(payloadManifest(files)) });
+}

package/src/plugin-loader.ts

@@ -5,6 +5,7 @@ import { Ajv } from 'ajv';
 import type { Step } from '@relayflows/surface';
 import { snapshotJsonValue } from './json-value.js';
 import { assertSupportedPlugin, PluginError, pluginPackageName, validatePluginManifest, type PluginManifest, type PluginVerb } from './plugin-manifest.js';
+import { isGithubPluginRef } from './plugin-source.js';
 
 export interface LoadedPlugin { readonly directory: string; readonly manifest: PluginManifest }
 export function findPluginProject(start: string): string | undefined {
@@ -47,8 +48,11 @@ export async function loadPlugins(start: string): Promise<readonly LoadedPlugin[
   if (config === null || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every(p => typeof p === 'string')))) {
     throw new PluginError('plugin_manifest_invalid', 'flows.json plugins must be package names.');
   }
+  // Flow extensions (github:… entries) are not helpers: the authored flow
+  // loader verifies and composes them (flow-extension-loader.ts). Here they
+  // are simply not helper packages, so they are left out of the helper set.
   const scope = join(root, 'node_modules/@flows');
-  const names = new Set<string>((config.plugins as string[] | undefined)?.map(pluginPackageName));
+  const names = new Set<string>((config.plugins as string[] | undefined)?.filter(p => !isGithubPluginRef(p)).map(pluginPackageName));
   if (existsSync(scope)) for (const name of readdirSync(scope).sort()) {
     if (name.startsWith('helper-') && !names.has(`@flows/${name}`)) {
       throw new PluginError('plugin_unlisted', `@flows/${name} is installed but not declared in flows.json plugins. Run flows add ${name}.`);

package/src/plugin-lock.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PluginError } from './plugin-manifest.js';
+import { SHA, canonicalPluginRef, isGithubPluginRef, parseCanonicalPluginRef, type PluginSourceRef } from './plugin-source.js';
+
+/**
+ * `flows.lock.json` — the project's plugin provenance. `flows.json.plugins`
+ * says *what* is declared; the lockfile says exactly which bytes that meant:
+ * the commit, the content digest, the manifest hash, and the order the
+ * operator declared. Version 2 is also the sealed bundle `lockfile.json`
+ * shape when the bundle carries plugins (RFC-0001 decision 14).
+ */
+export const PLUGIN_LOCK_FILE = 'flows.lock.json';
+export const PLUGIN_LOCK_VERSION = 2;
+const FLOWS_FILE = 'flows.json';
+
+export interface PluginLockEntry {
+  readonly name: string;
+  readonly kind: 'flow-extension';
+  readonly version: string;
+  readonly source: { readonly host: 'github'; readonly owner: string; readonly repo: string; readonly sha: string; readonly path: string };
+  /** sha256 of the payload manifest — the `@sha256:` in `.flows/plugins`. */
+  readonly digest: string;
+  /** sha256 of the `flows-plugin.json` bytes as installed. */
+  readonly manifestSha256: string;
+  /**
+   * 1-based position among the flow-extension (`github:`) entries of
+   * `flows.json.plugins`, in declaration order. Helper entries interspersed in
+   * that list do not count, so the order is the composition order exactly.
+   */
+  readonly order: number;
+  readonly resolvedAt: string;
+}
+export interface PluginLock { readonly version: 2; readonly plugins: readonly PluginLockEntry[] }
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const invalid = (message: string): never => { throw new PluginError('plugin_lock_invalid', `${PLUGIN_LOCK_FILE}: ${message}`); };
+
+export function parsePluginLock(input: unknown): PluginLock {
+  if (!object(input) || input.version !== PLUGIN_LOCK_VERSION || !Array.isArray(input.plugins)
+    || Object.keys(input).some(k => !['version', 'plugins'].includes(k))) return invalid(`expected { version: ${PLUGIN_LOCK_VERSION}, plugins: [] }.`);
+  const names = new Set<string>();
+  const plugins = input.plugins.map((entry, index) => {
+    if (!object(entry) || Object.keys(entry).sort().join(',') !== 'digest,kind,manifestSha256,name,order,resolvedAt,source,version'
+      || entry.kind !== 'flow-extension' || typeof entry.name !== 'string' || typeof entry.version !== 'string'
+      || typeof entry.digest !== 'string' || !HEX64.test(entry.digest)
+      || typeof entry.manifestSha256 !== 'string' || !HEX64.test(entry.manifestSha256)
+      || entry.order !== index + 1 || typeof entry.resolvedAt !== 'string' || Number.isNaN(Date.parse(entry.resolvedAt))
+      || !object(entry.source) || entry.source.host !== 'github' || typeof entry.source.owner !== 'string'
+      || typeof entry.source.repo !== 'string' || typeof entry.source.sha !== 'string' || !SHA.test(entry.source.sha)
+      || typeof entry.source.path !== 'string') return invalid(`plugins[${index}] is malformed.`);
+    if (names.has(entry.name)) return invalid(`plugin ${entry.name} is listed twice.`);
+    names.add(entry.name);
+    const source = parseCanonicalPluginRef(canonicalPluginRef({ host: 'github', owner: entry.source.owner, repo: entry.source.repo, ref: entry.source.sha, sha: entry.source.sha, path: entry.source.path }));
+    return Object.freeze({
+      name: entry.name, kind: 'flow-extension' as const, version: entry.version,
+      source: Object.freeze({ host: 'github' as const, owner: source.owner, repo: source.repo, sha: source.sha, path: source.path }),
+      digest: entry.digest, manifestSha256: entry.manifestSha256, order: entry.order, resolvedAt: entry.resolvedAt,
+    });
+  });
+  return Object.freeze({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze(plugins) });
+}
+
+/** Absent file → empty lock; unreadable or malformed → refusal. */
+export function readPluginLock(root: string): PluginLock {
+  recoverFlowsAndLock(root);
+  const path = join(root, PLUGIN_LOCK_FILE);
+  if (!existsSync(path)) return Object.freeze({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze([]) });
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return invalid('not valid JSON.'); }
+  return parsePluginLock(parsed);
+}
+
+export function writePluginLock(root: string, lock: PluginLock): void {
+  writeFileSync(join(root, PLUGIN_LOCK_FILE), `${JSON.stringify(parsePluginLock(lock), null, 2)}\n`);
+}
+
+/**
+ * Finish or abort a two-file update left by a process crash. The lock temp is
+ * written first: by itself it is only preparation and can be discarded. Once
+ * the config temp exists, both complete snapshots exist and recovery rolls
+ * them forward in the same lock-then-declaration order as the writer.
+ */
+export function recoverFlowsAndLock(root: string, configPath = join(root, FLOWS_FILE)): void {
+  const jsonTmp = `${configPath}.tmp`;
+  const lockPath = join(root, PLUGIN_LOCK_FILE);
+  const lockTmp = `${lockPath}.tmp`;
+  const hasJson = existsSync(jsonTmp);
+  const hasLock = existsSync(lockTmp);
+  if (!hasJson && !hasLock) return;
+  if (!hasJson) {
+    unlinkSync(lockTmp);
+    return;
+  }
+  let pendingConfig: unknown;
+  try { pendingConfig = JSON.parse(readFileSync(jsonTmp, 'utf8')); }
+  catch {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    return invalid('pending transaction has invalid flows.json.tmp.');
+  }
+  if (!object(pendingConfig) || !Array.isArray(pendingConfig.plugins)
+    || !pendingConfig.plugins.every(plugin => typeof plugin === 'string')) {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    return invalid('pending transaction has invalid flows.json.tmp.');
+  }
+  const lockSource = hasLock ? lockTmp : lockPath;
+  let pendingLock: unknown;
+  try { pendingLock = JSON.parse(readFileSync(lockSource, 'utf8')); }
+  catch {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    return invalid('pending transaction has no valid lock snapshot.');
+  }
+  try { parsePluginLock(pendingLock); }
+  catch (error) {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    throw error;
+  }
+  if (hasLock) renameSync(lockTmp, lockPath);
+  renameSync(jsonTmp, configPath);
+}
+
+/** Write complete snapshots, then recover them as one roll-forward transaction. */
+export function writeFlowsAndLock(root: string, configPath: string, config: Record<string, unknown>, plugins: readonly string[], lock: PluginLock): void {
+  const jsonTmp = `${configPath}.tmp`;
+  const lockPath = join(root, PLUGIN_LOCK_FILE);
+  const lockTmp = `${lockPath}.tmp`;
+  writeFileSync(lockTmp, `${JSON.stringify(parsePluginLock(lock), null, 2)}\n`);
+  writeFileSync(jsonTmp, `${JSON.stringify({ ...config, plugins: [...plugins] }, null, 2)}\n`);
+  recoverFlowsAndLock(root, configPath);
+}
+
+/**
+ * Rebuild the entry list in `flows.json.plugins` order: `order` is derived from
+ * the declaration list, never stored independently, so the two cannot disagree.
+ * Lock entries that are no longer declared are dropped; a declaration with no
+ * matching lock entry is a refusal.
+ */
+export function lockForDeclared(lock: PluginLock, declared: readonly string[]): PluginLock {
+  const byRef = new Map(lock.plugins.map(p => [canonicalPluginRef({ ...p.source, ref: p.source.sha }), p]));
+  const plugins = declared.filter(isGithubPluginRef).map((ref, index) => {
+    const found = byRef.get(ref);
+    if (found === undefined) return invalid(`flows.json declares ${ref} but the lockfile has no entry for it; run flows add ${ref}.`);
+    return Object.freeze({ ...found, order: index + 1 });
+  });
+  return Object.freeze({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze(plugins) });
+}
+
+export function lockWithPlugin(
+  lock: PluginLock, declared: readonly string[],
+  entry: Omit<PluginLockEntry, 'kind' | 'order'>,
+): PluginLock {
+  const byRef = new Map(lock.plugins.map(p => [canonicalPluginRef({ ...p.source, ref: p.source.sha }), p]));
+  byRef.set(canonicalPluginRef({ ...entry.source, ref: entry.source.sha }), { ...entry, kind: 'flow-extension', order: 0 });
+  return lockForDeclared({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze([...byRef.values()]) }, declared);
+}
+
+/** Lock entries paired with their declared reference, in declaration order. */
+export function lockedPlugins(lock: PluginLock): readonly { ref: string; entry: PluginLockEntry; source: PluginSourceRef }[] {
+  return lock.plugins.map(entry => {
+    const source = { ...entry.source, ref: entry.source.sha };
+    return { ref: canonicalPluginRef(source), entry, source };
+  });
+}
+
+/** The `github:` entries of `flows.json.plugins`, in declaration order; helper entries are left out. */
+export function declaredExtensionRefs(root: string): readonly string[] {
+  recoverFlowsAndLock(root);
+  let config: { plugins?: unknown };
+  try { config = JSON.parse(readFileSync(join(root, 'flows.json'), 'utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json.'); }
+  if (config === null || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every(p => typeof p === 'string')))) {
+    throw new PluginError('plugin_manifest_invalid', 'flows.json plugins must be strings.');
+  }
+  return Object.freeze(((config.plugins as string[] | undefined) ?? []).filter(isGithubPluginRef));
+}
+
+/**
+ * The three records that must agree before an extension is trusted:
+ * `flows.json.plugins` (declaration), `flows.lock.json` (provenance), and —
+ * checked by the caller against the returned digests — `.flows/plugins`
+ * (bytes). Any declaration without a lock entry, lock entry without a
+ * declaration, or order disagreement is `plugin_lock_invalid`.
+ */
+export function reconcileDeclaredExtensions(root: string): readonly { ref: string; entry: PluginLockEntry; source: PluginSourceRef }[] {
+  const declared = declaredExtensionRefs(root);
+  const locked = lockedPlugins(readPluginLock(root));
+  const lockedRefs = locked.map(p => p.ref);
+  for (const ref of declared) if (!lockedRefs.includes(ref)) throw new PluginError('plugin_lock_invalid', `flows.json declares ${ref} but flows.lock.json has no entry for it.`);
+  for (const ref of lockedRefs) if (!declared.includes(ref)) throw new PluginError('plugin_lock_invalid', `flows.lock.json records ${ref} but flows.json does not declare it.`);
+  if (declared.some((ref, index) => lockedRefs[index] !== ref)) throw new PluginError('plugin_lock_invalid', 'flows.lock.json order differs from flows.json.plugins.');
+  return locked;
+}

package/src/plugin-manifest.ts

@@ -5,6 +5,10 @@ export const PLUGIN_FAILURE_KINDS = [
   'plugin_unknown', 'plugin_unlisted', 'plugin_install_failed', 'plugin_manifest_missing',
   'plugin_manifest_invalid', 'plugin_preflight_missing', 'plugin_verb_unknown_primitive',
   'plugin_unsupported', 'plugin_credential_missing', 'plugin_server_unreachable',
+  // schema 2 flow extensions (see flow-extension-manifest.ts, plugin-source.ts, plugin-github.ts)
+  'plugin_kind_invalid', 'plugin_incompatible', 'plugin_event_unroutable', 'plugin_source_invalid',
+  'plugin_source_unresolved', 'plugin_fetch_failed', 'plugin_path_invalid', 'plugin_too_large',
+  'plugin_source_drift', 'plugin_lock_invalid',
 ] as const;
 export type PluginFailureKind = typeof PLUGIN_FAILURE_KINDS[number];
 export class PluginError extends Error {
@@ -16,6 +20,15 @@ export interface PluginVerb {
   lowersTo: 'run' | 'llm' | 'agent' | 'effect' | 'wait';
   args: Record<string, unknown>;
 }
+/** The kind a `flows-plugin.json` declares; absent means the schema-1 helper plugin. */
+export type PluginKind = 'helper' | 'flow-extension';
+export function pluginKindOf(input: unknown): PluginKind {
+  const kind = typeof input === 'object' && input !== null && !Array.isArray(input) ? (input as { kind?: unknown }).kind : undefined;
+  if (kind === undefined || kind === 'helper') return 'helper';
+  if (kind === 'flow-extension') return 'flow-extension';
+  throw new PluginError('plugin_kind_invalid', `Unknown plugin kind ${JSON.stringify(kind)}; expected "helper" or "flow-extension".`);
+}
+/** A schema-1 helper plugin: verbs that lower to kernel primitives. */
 export interface PluginManifest {
   name: string;
   version: string;
@@ -41,6 +54,10 @@ export function validatePluginManifest(input: unknown, packageName?: string): Pl
   catch { throw new PluginError('plugin_manifest_invalid', 'Plugin manifest must be JSON data.'); }
   const invalid = (message: string): never => { throw new PluginError('plugin_manifest_invalid', message); };
   if (!object(v)) return invalid('Expected a plugin manifest object.');
+  if (pluginKindOf(v) !== 'helper') {
+    throw new PluginError('plugin_kind_invalid', 'A flow-extension manifest installs from a GitHub reference (flows add github:<owner>/<repo>@<ref>#<path>), not as a helper package.');
+  }
+  if (v.schema !== undefined && v.schema !== 1) return invalid('Helper plugin manifests are schema 1.');
   if (!Object.hasOwn(v, 'preflight')) throw new PluginError('plugin_preflight_missing', 'Plugin must declare preflight.');
   if (typeof v.name !== 'string' || typeof v.version !== 'string' || !v.version.trim()) return invalid('Plugin name and version are required.');
   const resolved = pluginPackageName(v.name);

package/src/plugin-source.ts

@@ -0,0 +1,91 @@
+import { safePath } from './bundle.js';
+import { PluginError } from './plugin-manifest.js';
+
+/**
+ * Where a flow-extension plugin comes from: a public GitHub repository, pinned
+ * to a commit. A branch or tag is accepted as *input* only; what gets written
+ * to `flows.json` and the lockfile is always the canonical 40-hex form,
+ * `github:<owner>/<repo>@<sha>#<path>`, so a later reader can never resolve
+ * to different bytes than the installer saw.
+ */
+export interface PluginSourceInput {
+  readonly host: 'github';
+  readonly owner: string;
+  readonly repo: string;
+  /** Branch, tag, or commit as typed. */
+  readonly ref: string;
+  /** Directory inside the repository holding `flows-plugin.json`; `''` is the root. */
+  readonly path: string;
+}
+export interface PluginSourceRef extends PluginSourceInput {
+  /** Exactly 40 lowercase hex characters. */
+  readonly sha: string;
+}
+
+const OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const REPO = /^[A-Za-z0-9_.-]{1,100}$/;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/;
+export const SHA = /^[0-9a-f]{40}$/;
+
+function invalid(message: string): never {
+  throw new PluginError('plugin_source_invalid', message);
+}
+
+export function isGithubPluginRef(value: string): boolean {
+  return value.startsWith('github:') || /^https:\/\/github\.com\//.test(value);
+}
+
+/**
+ * Accepts `github:<owner>/<repo>@<ref>#<path>`,
+ * `https://github.com/<owner>/<repo>/tree/<ref>/<path>` (or `/blob/`), and
+ * `github:<owner>/<repo>@<ref>` for a root-level plugin.
+ *
+ * In the URL form the ref is the single segment after `tree/`: GitHub itself
+ * disambiguates `tree/feat/x/dir` against the repository's refs, which an
+ * offline parser cannot. A ref containing `/` must use the `github:` form,
+ * where `@ref#path` is unambiguous.
+ */
+export function parsePluginSource(input: string): PluginSourceInput {
+  if (input.length > 2048) return invalid('Plugin source is too long.');
+  let owner: string | undefined, repo: string | undefined, ref: string | undefined, path = '';
+  if (input.startsWith('github:')) {
+    const m = /^github:([^/@#]+)\/([^/@#]+)@([^#]+)(?:#(.*))?$/.exec(input);
+    if (!m) return invalid('Expected github:<owner>/<repo>@<ref>[#<path>].');
+    [, owner, repo, ref] = m;
+    path = m[4] ?? '';
+  } else if (/^https:\/\/github\.com\//.test(input)) {
+    let url: URL;
+    try { url = new URL(input); } catch { return invalid('Plugin source is not a valid URL.'); }
+    if (url.username || url.password || url.search || url.hash) return invalid('Plugin URL must not carry credentials, a query, or a fragment.');
+    const m = /^\/([^/]+)\/([^/]+)\/(?:tree|blob)\/([^/]+)(?:\/(.*))?$/.exec(url.pathname);
+    if (!m) return invalid('Expected https://github.com/<owner>/<repo>/tree/<ref>/<path>.');
+    try {
+      [, owner, repo, ref] = m.map(part => part === undefined ? part : decodeURIComponent(part));
+      path = m[4] === undefined ? '' : decodeURIComponent(m[4]);
+    } catch {
+      return invalid('Plugin URL contains invalid percent-encoding.');
+    }
+  } else return invalid('Expected a github: reference or a https://github.com/ URL.');
+  if (owner === undefined || !OWNER.test(owner)) return invalid('Invalid GitHub owner.');
+  if (repo === undefined || !REPO.test(repo) || repo === '.' || repo === '..') return invalid('Invalid GitHub repository name.');
+  if (repo.endsWith('.git')) repo = repo.slice(0, -4);
+  if (ref === undefined || !REF.test(ref) || ref.includes('..') || ref.endsWith('/') || ref.endsWith('.lock')) return invalid('Invalid git ref.');
+  path = path.replace(/\/+$/, '');
+  if (path !== '' && !safePath(path)) return invalid('Plugin path must be repository-relative without traversal.');
+  if (path.split('/').some(part => part === 'flows-plugin.json')) return invalid('Plugin path names the directory holding flows-plugin.json, not the file.');
+  return Object.freeze({ host: 'github', owner, repo, ref, path });
+}
+
+/** The one spelling that is ever persisted. */
+export function canonicalPluginRef(source: PluginSourceRef): string {
+  return `github:${source.owner}/${source.repo}@${source.sha}${source.path === '' ? '' : `#${source.path}`}`;
+}
+
+/** Parses a persisted reference; refuses anything but the canonical sha form. */
+export function parseCanonicalPluginRef(value: string): PluginSourceRef {
+  const parsed = parsePluginSource(value);
+  if (!value.startsWith('github:') || !SHA.test(parsed.ref)) {
+    throw new PluginError('plugin_source_invalid', `Persisted plugin reference must be github:<owner>/<repo>@<sha>[#<path>], got ${value}.`);
+  }
+  return Object.freeze({ ...parsed, sha: parsed.ref });
+}

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