@pulse-compute/cli 0.0.0 → 1.0.0-beta.1

package/src/provider-drivers.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-compiler/provider-toolchain');

package/src/target-support.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-compiler/project-target-support');

package/src/typescript-module-loader.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const { createRequire } = require('node:module');
+const ts = require('typescript');
+const {
+  JAVASCRIPT_APPLICATION_LOADER_VERSION,
+  isJavascriptApplicationPlan
+} = require('@pulse-compute/wasm-contracts/project/javascript-application');
+
+const TYPESCRIPT_MODULE_LOADER_VERSION = 'pulse.typescript-module-loader.v1';
+const PROJECT_HARNESS_VERSION = 'pulse.project-harness.v1';
+class PulseModuleLoadError extends Error {
+  constructor(code, message, detail = {}) { super(message); this.name = 'PulseModuleLoadError'; this.code = code; this.detail = Object.freeze({ ...detail }); }
+}
+function isInside(root, candidate) { const relative = path.relative(path.resolve(root), path.resolve(candidate)); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)); }
+function resolveRelative(fromFile, request) {
+  const base = path.resolve(path.dirname(fromFile), request);
+  const candidates = [base, ...['.ts','.tsx','.js','.cjs','.mjs','.json'].map((extension) => `${base}${extension}`), ...['.ts','.tsx','.js','.cjs','.mjs','.json'].map((extension) => path.join(base, `index${extension}`))];
+  return candidates.find((candidate) => { try { return fs.statSync(candidate).isFile(); } catch (_) { return false; } });
+}
+
+function canonicalExistingPath(value) {
+  const resolved = path.resolve(value);
+  return fs.existsSync(resolved)
+    ? fs.realpathSync(resolved)
+    : resolved;
+}
+
+function loadTypescriptModule(entryFile, options = {}) {
+  const entry = canonicalExistingPath(entryFile);
+  const workspaceRoot = canonicalExistingPath(
+    options.workspaceRoot || options.root || path.dirname(entry)
+  );
+  const allowedPackages = new Map(Object.entries(options.allowedPackages || {}));
+  const cache = new Map();
+  function load(file) {
+    const requested = path.resolve(file);
+    const resolved = fs.realpathSync(requested);
+    if (!isInside(workspaceRoot, resolved)) throw new PulseModuleLoadError('PULSE_TOOLING_MODULE_OUTSIDE_WORKSPACE', `Tooling module escapes the Pulse workspace: ${resolved}`, { workspaceRoot, file: resolved });
+    if (cache.has(resolved)) return cache.get(resolved).exports;
+    if (path.extname(resolved).toLowerCase() === '.json') { const value = JSON.parse(fs.readFileSync(resolved, 'utf8')); cache.set(resolved, { exports: value }); return value; }
+    const source = fs.readFileSync(resolved, 'utf8');
+    const transpiled = ts.transpileModule(source, { fileName: resolved, compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.CommonJS, moduleResolution: ts.ModuleResolutionKind.Node10, esModuleInterop: true, allowJs: true, resolveJsonModule: true }, reportDiagnostics: true });
+    const failures = (transpiled.diagnostics || []).filter((entry) => entry.category === ts.DiagnosticCategory.Error);
+    if (failures.length) throw new PulseModuleLoadError('PULSE_TOOLING_MODULE_COMPILE_FAILED', `Tooling module could not be compiled: ${resolved}`, { file: resolved, diagnostics: failures.map((entry) => ({ code: entry.code, message: ts.flattenDiagnosticMessageText(entry.messageText, '\n') })) });
+    const module = { exports: {} }; cache.set(resolved, module);
+    const localRequire = (request) => {
+      if (allowedPackages.has(request)) return allowedPackages.get(request);
+      if (request.startsWith('.') || request.startsWith('/')) {
+        const target = resolveRelative(resolved, request);
+        if (!target) throw new PulseModuleLoadError('PULSE_TOOLING_MODULE_IMPORT_NOT_FOUND', `Cannot resolve tooling import ${request} from ${resolved}.`, { request, from: resolved });
+        return load(target);
+      }
+      throw new PulseModuleLoadError('PULSE_TOOLING_MODULE_PACKAGE_UNSUPPORTED', `Tooling module package import is not allowed: ${request}`, { request, from: resolved });
+    };
+    new vm.Script(`(function(module,exports,require,__filename,__dirname){\n${transpiled.outputText}\n})`, { filename: resolved }).runInThisContext()(module, module.exports, localRequire, resolved, path.dirname(resolved));
+    return module.exports;
+  }
+  return Object.freeze({ version: TYPESCRIPT_MODULE_LOADER_VERSION, file: entry, exports: load(entryFile) });
+}
+function moduleDefault(exports) { return exports && Object.prototype.hasOwnProperty.call(exports, 'default') ? exports.default : exports; }
+function loadProjectHarness(file, options = {}) {
+  const loaded = loadTypescriptModule(file, options);
+  const exported = moduleDefault(loaded.exports);
+  const cases = Array.isArray(exported) ? exported : exported && Array.isArray(exported.cases) ? exported.cases : null;
+  if (!cases) throw new PulseModuleLoadError('PULSE_TEST_HARNESS_EXPORT_INVALID', 'Pulse test harness must export an ordered case array or an object with a cases array.');
+  return Object.freeze({ version: PROJECT_HARNESS_VERSION, file: loaded.file, cases: Object.freeze([...cases]) });
+}
+
+
+function sourceSha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function packageRequest(packageEntry, request) {
+  if (packageEntry.status !== 'package-runtime' || !packageEntry.runtimeEntry) return request;
+  if (!packageEntry.runtimeEntry.startsWith('.')) return packageEntry.runtimeEntry;
+  const suffix = packageEntry.runtimeEntry.replace(/^\.\/?/, '');
+  return suffix ? `${packageEntry.packageName}/${suffix}` : packageEntry.packageName;
+}
+
+function loadJavascriptApplication(plan, options = {}) {
+  if (!isJavascriptApplicationPlan(plan)) {
+    throw new PulseModuleLoadError('PULSE_JAVASCRIPT_APPLICATION_PLAN_INVALID', 'JavaScript application loading requires a normalized Pulse application plan.');
+  }
+  if (plan.loadable !== true) {
+    throw new PulseModuleLoadError(
+      plan.blockers[0]?.code || 'PULSE_JAVASCRIPT_APPLICATION_UNAVAILABLE',
+      plan.blockers[0]?.message || 'The JavaScript application plan has unresolved target blockers.',
+      { blockers: plan.blockers, planHash: plan.planHash, automaticFallback: false }
+    );
+  }
+  if (typeof options.validateApplication !== 'function') {
+    throw new TypeError('JavaScript application loading requires a provider application validator.');
+  }
+
+  const workspaceRoot = canonicalExistingPath( options.workspaceRoot || options.root || '.');
+  const modules = new Map(plan.graph.modules.map((entry) => [entry.id, entry]));
+  const packages = new Map(plan.packages.map((entry) => [entry.moduleId, entry]));
+  const runtimeEdges = new Map();
+  for (const edge of plan.graph.edges.filter((entry) => entry.runtime)) {
+    const key = `${edge.from}\u0000${edge.specifier}`;
+    if (runtimeEdges.has(key)) {
+      throw new PulseModuleLoadError(
+        'PULSE_JAVASCRIPT_GRAPH_EDGE_AMBIGUOUS',
+        `JavaScript application graph has more than one runtime edge for ${edge.specifier}.`,
+        { from: edge.from, specifier: edge.specifier }
+      );
+    }
+    runtimeEdges.set(key, edge);
+  }
+  const allowedPackages = new Map(Object.entries(options.allowedPackages || {}));
+  const workspaceRequire = options.require || createRequire(path.join(workspaceRoot, 'package.json'));
+  const cache = new Map();
+  const loadedPackages = new Set();
+
+  function loadPackage(target, edge) {
+    const packageEntry = packages.get(target.id);
+    if (!packageEntry) {
+      throw new PulseModuleLoadError(
+        'PULSE_JAVASCRIPT_PACKAGE_PLAN_MISSING',
+        `JavaScript application package ${target.packageName || edge.specifier} is absent from the target plan.`,
+        { moduleId: target.id, specifier: edge.specifier, source: edge.source }
+      );
+    }
+    if (packageEntry.status === 'unavailable') {
+      throw new PulseModuleLoadError(
+        packageEntry.reasonCode || 'PULSE_JAVASCRIPT_PACKAGE_REALIZATION_UNAVAILABLE',
+        `Package ${packageEntry.packageName} is unavailable under the JavaScript target.`,
+        { ...packageEntry, source: edge.source, automaticFallback: false }
+      );
+    }
+    const request = packageRequest(packageEntry, edge.specifier);
+    if (allowedPackages.has(edge.specifier)) {
+      loadedPackages.add(edge.specifier);
+      return allowedPackages.get(edge.specifier);
+    }
+    if (allowedPackages.has(request)) {
+      loadedPackages.add(request);
+      return allowedPackages.get(request);
+    }
+    try {
+      const value = workspaceRequire(request);
+      loadedPackages.add(request);
+      return value;
+    } catch (error) {
+      const code = error && error.code === 'ERR_REQUIRE_ESM'
+        ? 'PULSE_JAVASCRIPT_PACKAGE_ESM_UNSUPPORTED'
+        : 'PULSE_JAVASCRIPT_PACKAGE_MODULE_UNAVAILABLE';
+      throw new PulseModuleLoadError(
+        code,
+        `Cannot load JavaScript package import ${request} from ${edge.source?.file || plan.workspace.entry}.`,
+        { request, packageName: packageEntry.packageName, source: edge.source, causeCode: error && error.code }
+      );
+    }
+  }
+
+  function loadModule(moduleId) {
+    if (cache.has(moduleId)) return cache.get(moduleId).exports;
+    const moduleRecord = modules.get(moduleId);
+    if (!moduleRecord) throw new PulseModuleLoadError('PULSE_JAVASCRIPT_GRAPH_MODULE_MISSING', `Unknown JavaScript application module ${moduleId}.`, { moduleId });
+    if (moduleRecord.kind !== 'project') {
+      throw new PulseModuleLoadError('PULSE_JAVASCRIPT_APPLICATION_ENTRY_INVALID', 'The JavaScript application entry must be a project module.', { moduleId, kind: moduleRecord.kind });
+    }
+    const requested = path.resolve(workspaceRoot, moduleRecord.path);
+    if (!isInside(workspaceRoot, requested)) {
+      throw new PulseModuleLoadError('PULSE_JAVASCRIPT_MODULE_OUTSIDE_WORKSPACE', `JavaScript application module escapes the Pulse workspace: ${moduleRecord.path}`, { workspaceRoot, module: moduleRecord.path });
+    }
+    let resolved;
+    try {
+      resolved = fs.realpathSync(requested);
+    } catch (_) {
+      throw new PulseModuleLoadError('PULSE_JAVASCRIPT_MODULE_NOT_FOUND', `JavaScript application module is missing: ${moduleRecord.path}`, { workspaceRoot, module: moduleRecord.path });
+    }
+    if (!isInside(workspaceRoot, resolved)) {
+      throw new PulseModuleLoadError('PULSE_JAVASCRIPT_MODULE_OUTSIDE_WORKSPACE', `JavaScript application module resolves outside the Pulse workspace: ${moduleRecord.path}`, { workspaceRoot, module: moduleRecord.path, resolved });
+    }
+    if (path.extname(resolved).toLowerCase() === '.json') {
+      const bytes = fs.readFileSync(resolved);
+      if (sourceSha256(bytes) !== moduleRecord.contentHash) throw new PulseModuleLoadError('PULSE_JAVASCRIPT_MODULE_SOURCE_CHANGED', `JavaScript application module changed after planning: ${moduleRecord.path}`, { module: moduleRecord.path, expected: moduleRecord.contentHash, actual: sourceSha256(bytes) });
+      const value = JSON.parse(bytes.toString('utf8'));
+      cache.set(moduleId, { exports: value });
+      return value;
+    }
+    const source = fs.readFileSync(resolved, 'utf8');
+    const actualHash = sourceSha256(source);
+    if (actualHash !== moduleRecord.contentHash) {
+      throw new PulseModuleLoadError(
+        'PULSE_JAVASCRIPT_MODULE_SOURCE_CHANGED',
+        `JavaScript application module changed after planning: ${moduleRecord.path}`,
+        { module: moduleRecord.path, expected: moduleRecord.contentHash, actual: actualHash }
+      );
+    }
+    const transpiled = ts.transpileModule(source, {
+      fileName: resolved,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.CommonJS,
+        moduleResolution: ts.ModuleResolutionKind.Node10,
+        esModuleInterop: true,
+        allowJs: true,
+        resolveJsonModule: true
+      },
+      reportDiagnostics: true
+    });
+    const failures = (transpiled.diagnostics || []).filter((entry) => entry.category === ts.DiagnosticCategory.Error);
+    if (failures.length) {
+      throw new PulseModuleLoadError(
+        'PULSE_JAVASCRIPT_MODULE_COMPILE_FAILED',
+        `JavaScript application module could not be compiled: ${moduleRecord.path}`,
+        { module: moduleRecord.path, diagnostics: failures.map((entry) => ({ code: entry.code, message: ts.flattenDiagnosticMessageText(entry.messageText, '\n') })) }
+      );
+    }
+    const module = { exports: {} };
+    cache.set(moduleId, module);
+    const localRequire = (request) => {
+      const edge = runtimeEdges.get(`${moduleId}\u0000${request}`);
+      if (!edge) {
+        throw new PulseModuleLoadError(
+          'PULSE_JAVASCRIPT_IMPORT_NOT_IN_GRAPH',
+          `Runtime import ${request} is not present in the sealed reachable graph for ${moduleRecord.path}.`,
+          { request, from: moduleRecord.path, graphHash: plan.graph.graphHash }
+        );
+      }
+      const target = modules.get(edge.to);
+      if (!target) throw new PulseModuleLoadError('PULSE_JAVASCRIPT_GRAPH_MODULE_MISSING', `JavaScript application edge ${edge.id} has no target module.`, { edge });
+      if (target.kind === 'project') return loadModule(target.id);
+      if (target.kind === 'package') return loadPackage(target, edge);
+      if (target.kind === 'external') {
+        try {
+          return workspaceRequire(target.externalSpecifier || request);
+        } catch (error) {
+          throw new PulseModuleLoadError('PULSE_JAVASCRIPT_EXTERNAL_MODULE_UNAVAILABLE', `Cannot load external JavaScript module ${request}.`, { request, source: edge.source, causeCode: error && error.code });
+        }
+      }
+      throw new PulseModuleLoadError('PULSE_JAVASCRIPT_MODULE_KIND_UNSUPPORTED', `Unsupported JavaScript application module kind ${target.kind}.`, { target, edge });
+    };
+    new vm.Script(`(function(module,exports,require,__filename,__dirname){\n${transpiled.outputText}\n})`, { filename: resolved })
+      .runInThisContext()(module, module.exports, localRequire, resolved, path.dirname(resolved));
+    return module.exports;
+  }
+
+  const exports = loadModule(plan.graph.entryModuleId);
+  const application = moduleDefault(exports);
+  let validated;
+  try {
+    validated = options.validateApplication(application);
+  } catch (error) {
+    throw new PulseModuleLoadError(
+      error && error.code || 'PULSE_JAVASCRIPT_APPLICATION_EXPORT_INVALID',
+      error && error.message || 'Pulse JavaScript application default export is invalid.',
+      { entry: plan.workspace.entry, planHash: plan.planHash }
+    );
+  }
+  return Object.freeze({
+    version: JAVASCRIPT_APPLICATION_LOADER_VERSION,
+    plan,
+    application: validated,
+    entry: plan.workspace.entry,
+    modulesLoaded: cache.size,
+    packagesLoaded: Object.freeze([...loadedPackages].sort())
+  });
+}
+
+module.exports = Object.freeze({ TYPESCRIPT_MODULE_LOADER_VERSION, PROJECT_HARNESS_VERSION, JAVASCRIPT_APPLICATION_LOADER_VERSION, PulseModuleLoadError, loadTypescriptModule, moduleDefault, loadProjectHarness, loadJavascriptApplication });

package/src/workflow.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const path = require('node:path');
+const {
+  CONFIG_FILE_NAMES,
+  PulseProjectError
+} = require('./project-config.js');
+const { exitCodeForDiagnostic } = require('./diagnostics.js');
+const { COMMANDS, renderUsage } = require('./command-spec.js');
+const { parseCommandRequest, normalizeCommandRequest } = require('./internal/command-request.js');
+const { commandRequiresProjectContext, resolveProjectContext } = require('./internal/project-context.js');
+const { createCommandPlan } = require('./internal/command-plan.js');
+const {
+  executeCommandPlan,
+  summarizeExecutionError
+} = require('./internal/command-executor.js');
+const { createCommandReporter } = require('./internal/command-reporter.js');
+
+const CLI_VERSION = require('../package.json').version;
+
+function usage() {
+  return renderUsage({ version: CLI_VERSION, configFiles: CONFIG_FILE_NAMES });
+}
+
+function planningOptions(request, cwd, projectContext) {
+  return {
+    cwd,
+    version: CLI_VERSION,
+    projectContext
+  };
+}
+
+async function runPulseWorkflowCli(argv, io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  const cwd = path.resolve(io.cwd || process.cwd());
+  const environment = io.env || process.env;
+  const reporter = createCommandReporter({
+    stdout,
+    stderr,
+    cliVersion: CLI_VERSION,
+    usageText: usage()
+  });
+  let request;
+  try {
+    request = parseCommandRequest(argv);
+    if (request.kind === 'command' && request.help) request = normalizeCommandRequest({ help: true });
+    const projectContext = commandRequiresProjectContext(request)
+      ? resolveProjectContext(request, { cwd, environment })
+      : undefined;
+    const plan = createCommandPlan(request, planningOptions(request, cwd, projectContext));
+    if (request.kind === 'command' && request.dryRun) {
+      reporter.reportPlan(request, plan);
+      return { status: 0, plan };
+    }
+    const execution = await executeCommandPlan(plan, request, {
+      projectContext,
+      environment,
+      cliVersion: CLI_VERSION,
+      onEvent: (event) => reporter.reportEvent(request, event)
+    });
+    return reporter.reportExecution(request, plan, execution);
+  } catch (error) {
+    const summary = summarizeExecutionError(error);
+    reporter.reportDiagnostic(summary, { request, argv });
+    return {
+      status: exitCodeForDiagnostic(summary.code, error instanceof PulseProjectError ? 2 : 1),
+      error: summary
+    };
+  }
+}
+
+module.exports = {
+  CLI_VERSION,
+  COMMANDS,
+  runPulseWorkflowCli,
+  usage
+};

package/src/workspace.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const WORKSPACE_DISCOVERY_VERSION = 'pulse.workspace-discovery.v1';
+const PROJECT_WORKSPACE_VERSION = 'pulse.project-workspace.v1';
+const CONVENTIONAL_CONFIG = path.join('.pulse', 'config.ts');
+
+class PulseWorkspaceError extends Error {
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = 'PulseWorkspaceError';
+    this.code = code;
+    this.detail = Object.freeze({ ...detail });
+  }
+}
+function fileExists(file) { try { return fs.statSync(file).isFile(); } catch (_) { return false; } }
+function directoryExists(dir) { try { return fs.statSync(dir).isDirectory(); } catch (_) { return false; } }
+function canonicalDirectory(dir) { return fs.realpathSync(path.resolve(dir)); }
+function canonicalExistingFile(file) { return fs.realpathSync(path.resolve(file)); }
+function isInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function findWorktreeBoundary(start) {
+  let current = canonicalDirectory(start);
+  for (;;) {
+    if (fs.existsSync(path.join(current, '.git'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+}
+function discoverConventionalWorkspace(start) {
+  const origin = canonicalDirectory(start);
+  const boundary = findWorktreeBoundary(origin);
+  let current = origin;
+  for (;;) {
+    const configFile = path.join(current, CONVENTIONAL_CONFIG);
+    if (fileExists(configFile)) {
+      return Object.freeze({
+        version: PROJECT_WORKSPACE_VERSION,
+        kind: 'conventional',
+        root: current,
+        configFile: canonicalExistingFile(configFile),
+        discoveryStart: origin,
+        boundary,
+        source: current === origin ? 'current' : 'ancestor',
+        configInsideWorkspace: true
+      });
+    }
+    if (current === boundary) break;
+    const parent = path.dirname(current);
+    if (parent === current || !isInside(boundary, parent)) break;
+    current = parent;
+  }
+  return undefined;
+}
+function resolveWorkspace(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const startCandidate = options.directory ? path.resolve(cwd, options.directory) : cwd;
+  if (!directoryExists(startCandidate)) {
+    throw new PulseWorkspaceError('PULSE_PROJECT_ROOT_MISSING', `Pulse project directory does not exist: ${startCandidate}`, { projectRoot: startCandidate });
+  }
+  const start = canonicalDirectory(startCandidate);
+  return discoverConventionalWorkspace(start);
+}
+
+module.exports = Object.freeze({
+  WORKSPACE_DISCOVERY_VERSION,
+  PROJECT_WORKSPACE_VERSION,
+  CONVENTIONAL_CONFIG,
+  PulseWorkspaceError,
+  fileExists,
+  directoryExists,
+  isInside,
+  findWorktreeBoundary,
+  discoverConventionalWorkspace,
+  resolveWorkspace,
+  resolveProjectWorkspace: resolveWorkspace
+});