@xdelivered/emberflow 0.2.0 → 0.5.0

package/dist/server/sourceNav.js

@@ -0,0 +1,503 @@
+import { readFileSync, statSync } from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { isPathWithin } from './pathSafety.js';
+// ---------------------------------------------------------------------------
+// Lazy typescript module
+let tsModulePromise;
+async function loadTs(loader) {
+    if (loader) {
+        try {
+            return await loader();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!tsModulePromise) {
+        tsModulePromise = import('typescript').then((m) => (m.default ?? m));
+    }
+    try {
+        return await tsModulePromise;
+    }
+    catch {
+        tsModulePromise = undefined; // allow a later retry (e.g. install completed)
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Path guards
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+function languageOf(file) {
+    return TS_EXTS.has(extname(file)) ? 'ts' : 'js';
+}
+/** Deny-list beyond isPathWithin: node_modules anywhere, secret basenames. */
+function isRequestPathAllowed(projectRoot, rel) {
+    if (!isPathWithin(projectRoot, rel))
+        return false;
+    const segments = rel.split('/');
+    if (segments.includes('node_modules'))
+        return false;
+    const base = (segments[segments.length - 1] ?? '').toLowerCase();
+    if (base.startsWith('.env'))
+        return false;
+    if (base === 'emberflow.secrets.json')
+        return false;
+    if (base.endsWith('.pem') || base.endsWith('.key'))
+        return false;
+    return true;
+}
+const parseCache = new Map();
+/** Clears all sourceNav caches (parse, tsconfig, ts module) — tests only. */
+export function resetSourceNavCaches() {
+    parseCache.clear();
+    tsconfigCache.clear();
+    tsModulePromise = undefined;
+}
+function scriptKindFor(ts, file) {
+    switch (extname(file)) {
+        case '.ts':
+        case '.mts':
+        case '.cts':
+            return ts.ScriptKind.TS;
+        case '.tsx':
+            return ts.ScriptKind.TSX;
+        case '.jsx':
+            return ts.ScriptKind.JSX;
+        default:
+            return ts.ScriptKind.JS;
+    }
+}
+function parseFile(ts, absPath, content) {
+    const sf = ts.createSourceFile(absPath, content, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, scriptKindFor(ts, absPath));
+    const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+    const hasExportModifier = (node) => {
+        const mods = node.modifiers;
+        return !!mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    };
+    const declarations = [];
+    const imports = [];
+    const reexports = [];
+    const dynamicImports = [];
+    /** Names exported post-hoc via a specifier-less `export { x }`. */
+    const localExports = new Set();
+    for (const stmt of sf.statements) {
+        if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+            declarations.push({
+                name: stmt.name.text,
+                kind: 'fn',
+                line: lineOf(stmt.getStart(sf)),
+                endLine: lineOf(stmt.end),
+                exported: hasExportModifier(stmt),
+            });
+        }
+        else if (ts.isClassDeclaration(stmt) && stmt.name) {
+            declarations.push({
+                name: stmt.name.text,
+                kind: 'class',
+                line: lineOf(stmt.getStart(sf)),
+                endLine: lineOf(stmt.end),
+                exported: hasExportModifier(stmt),
+            });
+        }
+        else if (ts.isVariableStatement(stmt)) {
+            for (const decl of stmt.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.initializer) {
+                    declarations.push({
+                        name: decl.name.text,
+                        kind: 'const',
+                        line: lineOf(decl.getStart(sf)),
+                        endLine: lineOf(stmt.end),
+                        exported: hasExportModifier(stmt),
+                    });
+                }
+            }
+        }
+        else if (ts.isInterfaceDeclaration(stmt) ||
+            ts.isTypeAliasDeclaration(stmt) ||
+            ts.isEnumDeclaration(stmt)) {
+            declarations.push({
+                name: stmt.name.text,
+                kind: 'other',
+                line: lineOf(stmt.getStart(sf)),
+                endLine: lineOf(stmt.end),
+                exported: hasExportModifier(stmt),
+            });
+        }
+        else if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier)) {
+            const from = stmt.moduleSpecifier.text;
+            const clause = stmt.importClause;
+            if (!clause) {
+                imports.push({ name: '*', local: '', from }); // side-effect import
+                continue;
+            }
+            if (clause.name)
+                imports.push({ name: 'default', local: clause.name.text, from });
+            const bindings = clause.namedBindings;
+            if (bindings) {
+                if (ts.isNamespaceImport(bindings)) {
+                    imports.push({ name: '*', local: bindings.name.text, from });
+                }
+                else {
+                    for (const el of bindings.elements) {
+                        imports.push({ name: (el.propertyName ?? el.name).text, local: el.name.text, from });
+                    }
+                }
+            }
+        }
+        else if (ts.isExportDeclaration(stmt)) {
+            const spec = stmt.moduleSpecifier;
+            if (spec && ts.isStringLiteral(spec)) {
+                const from = spec.text;
+                if (!stmt.exportClause) {
+                    reexports.push({ exported: '*', from });
+                }
+                else if (ts.isNamespaceExport(stmt.exportClause)) {
+                    reexports.push({ exported: stmt.exportClause.name.text, source: '*', from });
+                }
+                else {
+                    for (const el of stmt.exportClause.elements) {
+                        reexports.push({
+                            exported: el.name.text,
+                            source: (el.propertyName ?? el.name).text,
+                            from,
+                        });
+                    }
+                }
+            }
+            else if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+                for (const el of stmt.exportClause.elements) {
+                    localExports.add((el.propertyName ?? el.name).text);
+                }
+            }
+        }
+    }
+    // `export { x }` after the declaration marks it exported.
+    for (const d of declarations) {
+        if (!d.exported && localExports.has(d.name))
+            d.exported = true;
+    }
+    // Dynamic imports live anywhere in the tree.
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            const arg = node.arguments[0];
+            dynamicImports.push(arg && ts.isStringLiteral(arg) ? { from: arg.text } : {});
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return { content, language: languageOf(absPath), declarations, imports, dynamicImports, reexports };
+}
+/** Parse (or reuse the cached parse of) an absolute path. Throws when unreadable. */
+function getParsed(ts, absPath) {
+    const stat = statSync(absPath);
+    const cached = parseCache.get(absPath);
+    if (cached && cached.mtimeMs === stat.mtimeMs)
+        return cached.parsed;
+    const content = readFileSync(absPath, 'utf8');
+    const parsed = parseFile(ts, absPath, content);
+    parseCache.set(absPath, { mtimeMs: stat.mtimeMs, parsed });
+    return parsed;
+}
+function getParsedSafe(ts, absPath) {
+    try {
+        return getParsed(ts, absPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Specifier resolution
+const RESOLVE_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs'];
+/** TS-style specifier mapping: an emitted-extension specifier may point at TS source. */
+const JS_TO_TS = {
+    '.js': ['.ts', '.tsx'],
+    '.mjs': ['.mts'],
+    '.cjs': ['.cts'],
+};
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Extension ladder: exact → +ext → TS .js→.ts mapping → /index.*  */
+function resolveWithLadder(base) {
+    if (isFile(base))
+        return base;
+    for (const ext of RESOLVE_EXTS) {
+        if (isFile(base + ext))
+            return base + ext;
+    }
+    for (const [jsExt, tsExts] of Object.entries(JS_TO_TS)) {
+        if (base.endsWith(jsExt)) {
+            const stem = base.slice(0, -jsExt.length);
+            for (const tsExt of tsExts) {
+                if (isFile(stem + tsExt))
+                    return stem + tsExt;
+            }
+        }
+    }
+    for (const ext of RESOLVE_EXTS) {
+        const idx = join(base, 'index' + ext);
+        if (isFile(idx))
+            return idx;
+    }
+    return undefined;
+}
+const tsconfigCache = new Map();
+function tsconfigPathsFor(ts, projectRoot) {
+    const cfgPath = join(projectRoot, 'tsconfig.json');
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(cfgPath).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+    const cached = tsconfigCache.get(cfgPath);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.paths;
+    let paths;
+    try {
+        // ts.readConfigFile parses leniently — tsconfig.json is JSONC.
+        const { config } = ts.readConfigFile(cfgPath, (p) => readFileSync(p, 'utf8'));
+        const options = config
+            ?.compilerOptions;
+        const rawPaths = options?.paths;
+        if (rawPaths && typeof rawPaths === 'object') {
+            const entries = [];
+            for (const [pattern, targetsRaw] of Object.entries(rawPaths)) {
+                if (!Array.isArray(targetsRaw))
+                    continue;
+                const targets = targetsRaw.filter((t) => typeof t === 'string');
+                const stars = pattern.split('*').length - 1;
+                if (stars === 0) {
+                    entries.push({ prefix: '', suffix: '', exact: pattern, targets });
+                }
+                else if (stars === 1) {
+                    const [prefix = '', suffix = ''] = pattern.split('*');
+                    entries.push({ prefix, suffix, targets });
+                }
+                // multi-star patterns are invalid tsconfig anyway — ignored
+            }
+            // Longest prefix wins, mirroring TS's matching order.
+            entries.sort((a, b) => (b.exact ?? b.prefix).length - (a.exact ?? a.prefix).length);
+            paths = { base: resolve(projectRoot, options?.baseUrl ?? '.'), entries };
+        }
+    }
+    catch {
+        paths = undefined;
+    }
+    tsconfigCache.set(cfgPath, { mtimeMs, paths });
+    return paths;
+}
+function resolveViaTsconfigPaths(ts, projectRoot, spec) {
+    const cfg = tsconfigPathsFor(ts, projectRoot);
+    if (!cfg)
+        return undefined;
+    for (const entry of cfg.entries) {
+        let substituted;
+        if (entry.exact !== undefined) {
+            if (spec === entry.exact)
+                substituted = entry.targets;
+        }
+        else if (spec.startsWith(entry.prefix) &&
+            spec.endsWith(entry.suffix) &&
+            spec.length >= entry.prefix.length + entry.suffix.length) {
+            const middle = spec.slice(entry.prefix.length, spec.length - entry.suffix.length);
+            substituted = entry.targets.map((t) => t.replace('*', middle));
+        }
+        if (!substituted)
+            continue;
+        for (const target of substituted) {
+            const found = resolveWithLadder(resolve(cfg.base, target));
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+const NODE_BUILTINS = new Set(builtinModules);
+/** Repo-relative POSIX path when `abs` sits inside the root (and outside node_modules). */
+function projectRelative(projectRoot, abs) {
+    const rel = relative(projectRoot, abs);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return undefined;
+    if (rel.split('/').includes('node_modules'))
+        return undefined;
+    return rel;
+}
+/**
+ * Resolve a specifier from `importerAbs`. Project results carry the ABSOLUTE
+ * target path in `absPath` (for chain following); callers convert to
+ * repo-relative for the response.
+ */
+function resolveSpecifier(ts, projectRoot, importerAbs, spec) {
+    if (spec.startsWith('./') || spec.startsWith('../')) {
+        const target = resolveWithLadder(resolve(dirname(importerAbs), spec));
+        if (!target)
+            return { kind: 'unresolved', reason: `cannot resolve relative import '${spec}'` };
+        const rel = projectRelative(projectRoot, target);
+        if (!rel)
+            return { kind: 'unresolved', reason: 'resolves outside the project root' };
+        return { kind: 'project', path: rel, absPath: target };
+    }
+    if (isAbsolute(spec))
+        return { kind: 'unresolved', reason: 'absolute-path specifier' };
+    if (spec.startsWith('node:'))
+        return { kind: 'builtin' };
+    const viaPaths = resolveViaTsconfigPaths(ts, projectRoot, spec);
+    if (viaPaths) {
+        const rel = projectRelative(projectRoot, viaPaths);
+        if (!rel)
+            return { kind: 'unresolved', reason: 'resolves outside the project root' };
+        return { kind: 'project', path: rel, absPath: viaPaths };
+    }
+    if (NODE_BUILTINS.has(spec))
+        return { kind: 'builtin' };
+    const parts = spec.split('/');
+    const pkg = spec.startsWith('@') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+    return { kind: 'external', package: pkg };
+}
+// ---------------------------------------------------------------------------
+// Re-export chain following
+const REEXPORT_DEPTH_CAP = 8;
+/**
+ * Find the file+line where `exportName` is actually DECLARED, starting at
+ * `absFile` and following named/star re-exports. Depth-capped, cycle-safe.
+ */
+function findExportedDeclaration(ts, projectRoot, absFile, exportName, depth = 0, seen = new Set()) {
+    if (depth > REEXPORT_DEPTH_CAP)
+        return undefined;
+    const key = `${absFile}::${exportName}`;
+    if (seen.has(key))
+        return undefined;
+    seen.add(key);
+    const parsed = getParsedSafe(ts, absFile);
+    if (!parsed)
+        return undefined;
+    const decl = parsed.declarations.find((d) => d.exported && d.name === exportName) ??
+        parsed.declarations.find((d) => d.name === exportName);
+    if (decl)
+        return { absFile, line: decl.line };
+    const named = parsed.reexports.find((r) => r.exported === exportName && r.source && r.source !== '*');
+    if (named) {
+        const res = resolveSpecifier(ts, projectRoot, absFile, named.from);
+        if (res.kind === 'project' && res.absPath) {
+            return findExportedDeclaration(ts, projectRoot, res.absPath, named.source, depth + 1, seen);
+        }
+        return undefined;
+    }
+    for (const star of parsed.reexports.filter((r) => r.exported === '*')) {
+        const res = resolveSpecifier(ts, projectRoot, absFile, star.from);
+        if (res.kind !== 'project' || !res.absPath)
+            continue;
+        const found = findExportedDeclaration(ts, projectRoot, res.absPath, exportName, depth + 1, seen);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** Resolution for an import/re-export entry, chased to the declaring file when possible. */
+function resolveEntry(ts, projectRoot, importerAbs, spec, symbolName) {
+    const res = resolveSpecifier(ts, projectRoot, importerAbs, spec);
+    if (res.kind !== 'project' || !res.absPath) {
+        const { absPath: _drop, ...pub } = res;
+        return pub;
+    }
+    if (symbolName && symbolName !== '*' && symbolName !== 'default') {
+        const found = findExportedDeclaration(ts, projectRoot, res.absPath, symbolName);
+        if (found) {
+            const rel = projectRelative(projectRoot, found.absFile);
+            if (rel)
+                return { kind: 'project', path: rel, line: found.line };
+        }
+    }
+    return { kind: 'project', path: res.path };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+export async function getSourceFile(projectRoot, relPath, opts) {
+    const root = resolve(projectRoot);
+    // Generic 400: never echo the requested path back to the client.
+    if (typeof relPath !== 'string' || !isRequestPathAllowed(root, relPath)) {
+        return { ok: false, status: 400, error: 'Invalid or denied path' };
+    }
+    const abs = resolve(root, relPath);
+    let stat;
+    try {
+        stat = await fsp.stat(abs);
+    }
+    catch {
+        return { ok: false, status: 404, error: 'File not found' };
+    }
+    if (!stat.isFile())
+        return { ok: false, status: 404, error: 'File not found' };
+    const responsePath = relative(root, abs);
+    const ts = await loadTs(opts?.tsLoader);
+    if (!ts) {
+        const content = await fsp.readFile(abs, 'utf8');
+        return {
+            ok: true,
+            payload: {
+                path: responsePath,
+                content,
+                language: languageOf(abs),
+                resolver: 'unavailable',
+                symbols: { declarations: [], imports: [], reexports: [] },
+            },
+        };
+    }
+    let parsed;
+    try {
+        parsed = getParsed(ts, abs);
+    }
+    catch {
+        return { ok: false, status: 404, error: 'File not found' };
+    }
+    const imports = parsed.imports.map((raw) => ({
+        name: raw.name,
+        local: raw.local,
+        from: raw.from,
+        resolution: resolveEntry(ts, root, abs, raw.from, raw.name),
+    }));
+    for (const dyn of parsed.dynamicImports) {
+        if (dyn.from !== undefined) {
+            imports.push({
+                name: 'import()',
+                local: '',
+                from: dyn.from,
+                resolution: resolveEntry(ts, root, abs, dyn.from, undefined),
+            });
+        }
+        else {
+            imports.push({
+                name: 'import()',
+                local: '',
+                from: '(computed)',
+                resolution: { kind: 'unresolved', reason: 'dynamic import with a computed specifier' },
+            });
+        }
+    }
+    const reexports = parsed.reexports.map((raw) => ({
+        name: raw.exported,
+        from: raw.from,
+        resolution: resolveEntry(ts, root, abs, raw.from, raw.source && raw.source !== '*' ? raw.source : undefined),
+    }));
+    return {
+        ok: true,
+        payload: {
+            path: responsePath,
+            content: parsed.content,
+            language: parsed.language,
+            symbols: { declarations: parsed.declarations, imports, reexports },
+        },
+    };
+}

package/dist/server/subflowRunner.d.ts

@@ -1,6 +1,42 @@
-import type { LogLine, NodeRegistry, StartRunOptions, TraceSink, WorkflowDefinition } from '../src/engine/index.js';
+import type { FlowRun, LogLine, NodeRegistry, NodeRunState, StartRunOptions, TraceSink, WorkflowDefinition, WorkflowRun } from '../src/engine/index.js';
 /** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
 export declare const SUBFLOW_DEPTH_CAP = 8;
+/**
+ * One live drilled-into child on a stepped run. Pushed by the subflow runner
+ * when a Subflow node starts its child; popped by the registry's composite
+ * step() when the child's own stepping completes. `resolve`/`reject` settle
+ * the promise the parent's Subflow node execution is blocked on.
+ */
+export interface DrillEntry {
+    handle: FlowRun;
+    /** The child flow's id (what the caller drilled into). */
+    workflowId: string;
+    /** The parent Subflow node that triggered the child. */
+    viaNodeId: string;
+    /** Hands the completed child run back to the blocked parent Subflow node. */
+    resolve: (run: WorkflowRun) => void;
+    reject: (err: unknown) => void;
+    /**
+     * This level's own executor.step() promise, left pending while a DEEPER
+     * child runs (a Subflow node's execution blocks on its child). Stashed by
+     * the registry when it observes `entered`; folded back in on exit.
+     */
+    pendingStep?: Promise<boolean>;
+}
+/**
+ * Per-root-run drill state for stepped runs. The root's subflow runner and
+ * every nested child's runner share the SAME instance, so grandchildren push
+ * onto the same stack and nesting Just Works.
+ */
+export interface DrillState {
+    stack: DrillEntry[];
+    /** Armed by the registry's step() while it awaits a level's step, so a
+     *  child starting can be raced against the (now blocked) step promise. */
+    onChildStarted?: (entry: DrillEntry) => void;
+    /** Set by RunRegistry.cancel(): unwinding parent executions must not start
+     *  (or block on) new children — runSubflow fails fast instead. */
+    cancelled?: boolean;
+}
 export interface SubflowRunnerOptions {
     /** Resolves a child workflow by id (server hosts this via apiStore.load). */
     loadFlow: (id: string) => WorkflowDefinition | undefined;
@@ -19,6 +55,17 @@ export interface SubflowRunnerOptions {
      *  prefixed with the child flow's name and the caller node's id, exactly as
      *  the live runner streams them over SSE. Absent for headless runs. */
     onLog?: (line: LogLine) => void;
+    /**
+     * Present only for stepped runs: children become step-drivable instead of
+     * running to completion. The runner pushes each started child onto
+     * `drill.stack` and blocks the Subflow node until the registry pops it.
+     */
+    drill?: DrillState;
+    /** Child nodeState forwarder for stepped runs — receives the CHILD flow's
+     *  id so the client can route states to the drilled-in view. Only wired
+     *  when `drill` is present (non-stepped children keep today's behavior:
+     *  their node states are discarded, only the output returns). */
+    onNodeState?: (workflowId: string, nodeId: string, state: NodeRunState) => void;
 }
 /**
  * Shared Subflow-runner factory used by BOTH the live runner

package/dist/server/subflowRunner.js

@@ -12,6 +12,11 @@ export const SUBFLOW_DEPTH_CAP = 8;
  */
 export function makeSubflowRunner(opts, ancestry) {
     return async (workflowId, input, callerNodeId) => {
+        // A cancelled stepped run's unwinding parents (their runSubflow was
+        // rejected) may retry: never push a new child that nothing will step.
+        if (opts.drill?.cancelled) {
+            return { status: 'failed', error: 'run cancelled' };
+        }
         if (ancestry.length >= SUBFLOW_DEPTH_CAP) {
             return { status: 'failed', error: `subflow depth cap (${SUBFLOW_DEPTH_CAP}) exceeded` };
         }
@@ -40,17 +45,39 @@ export function makeSubflowRunner(opts, ancestry) {
                 mocks: childFlow.mocks ?? {},
                 trace: opts.trace,
                 subflowRunner: makeSubflowRunner(opts, [...ancestry, workflowId]),
-                events: opts.onLog
+                events: opts.onLog || (opts.drill && opts.onNodeState)
                     ? {
-                        onLog: (line) => opts.onLog({
-                            ...line,
-                            nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
-                            nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
-                        }),
+                        ...(opts.onLog
+                            ? {
+                                onLog: (line) => opts.onLog({
+                                    ...line,
+                                    nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
+                                    nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
+                                }),
+                            }
+                            : {}),
+                        // Stepped children stream their node states into the ROOT
+                        // run's SSE stream, tagged with the child flow's id.
+                        ...(opts.drill && opts.onNodeState
+                            ? {
+                                onNodeStateChange: (nodeId, state) => opts.onNodeState(childFlow.id, nodeId, state),
+                            }
+                            : {}),
                     }
                     : undefined,
             });
-            const childRun = await childHandle.runToEnd();
+            // Stepped run: don't run the child here. Push it onto the shared drill
+            // stack and block this Subflow node until the registry's composite
+            // step() drives the child to completion and pops the entry — resolving
+            // with the completed child run, which flows into the exact same
+            // output-extraction / failure-mapping path runToEnd feeds today.
+            const childRun = opts.drill
+                ? await new Promise((resolve, reject) => {
+                    const entry = { handle: childHandle, workflowId, viaNodeId: callerNodeId, resolve, reject };
+                    opts.drill.stack.push(entry);
+                    opts.drill.onChildStarted?.(entry);
+                })
+                : await childHandle.runToEnd();
             if (childRun.status !== 'succeeded') {
                 // Surface the child's actual failure (e.g. the Mock-mode "would touch
                 // real infrastructure" boundary message) through the Subflow node's

package/dist/server/updateCheck.d.ts

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process';
+/**
+ * Update notifier + installer plumbing for consumer projects (they install
+ * @xdelivered/emberflow from npm and run `npx emberflow dev`).
+ *
+ * - checkForUpdate: asks the npm registry for the latest published version and
+ *   compares it against the running one. Fail-SILENT by design: any network,
+ *   HTTP, or parse failure returns null — an update nudge must never break or
+ *   slow the studio. Results (including failures) are cached in-memory for an
+ *   hour so /update-status stays cheap and the registry isn't hammered.
+ * - runNpmInstall: the actual one-click updater — `npm install <pkg>@latest`
+ *   spawned (no shell) in the project root. Injectable spawn for tests.
+ */
+export declare const EMBERFLOW_PACKAGE = "@xdelivered/emberflow";
+export interface UpdateCheckResult {
+    current: string;
+    latest: string;
+    updateAvailable: boolean;
+}
+export interface CheckForUpdateOpts {
+    /** Registry base URL. Defaults to EMBERFLOW_REGISTRY env, then npmjs. */
+    registry?: string;
+    /** Cache TTL in ms (default 1h). */
+    ttlMs?: number;
+    /** Injectable clock for TTL tests. */
+    now?: () => number;
+    /** Injectable fetch for tests. */
+    fetchFn?: typeof fetch;
+}
+/** Test hook: clear the in-memory check cache. */
+export declare function resetUpdateCheckCache(): void;
+/**
+ * Latest-version check against the npm registry. Returns null when the check
+ * is disabled (EMBERFLOW_UPDATE_CHECK=0) or unavailable for ANY reason —
+ * never throws.
+ */
+export declare function checkForUpdate(currentVersion: string, opts?: CheckForUpdateOpts): Promise<UpdateCheckResult | null>;
+/**
+ * The running package's own version, read from its package.json. Two layouts,
+ * same probe as prompt.ts's EMBERFLOW_BIN: in the source repo this file is
+ * server/updateCheck.ts and the package root is one level up; in the shipped
+ * package it runs from dist/server/updateCheck.js and the root is two up.
+ */
+export declare function ownVersion(): string | null;
+/**
+ * True when the consumer's node_modules/@xdelivered/emberflow is a symlink —
+ * a `file:`/`npm link` dev setup that an npm install would clobber. POST
+ * /update refuses in that case.
+ */
+export declare function isLinkedInstall(projectRoot: string): boolean;
+export type InstallResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface RunNpmInstallOpts {
+    /** Injectable spawner so tests never actually npm install. */
+    spawnFn?: typeof spawn;
+    /** Kill-and-fail deadline (default 5min). */
+    timeoutMs?: number;
+}
+/**
+ * Runs `npm install @xdelivered/emberflow@latest` in the project root via
+ * spawn (no shell). Captures the last ~4KB of combined output; on failure
+ * that tail is the error. Never rejects.
+ */
+export declare function runNpmInstall(projectRoot: string, opts?: RunNpmInstallOpts): Promise<InstallResult>;