@uipath/project-executor 1.200.0-preview.118

package/README.md

@@ -0,0 +1,131 @@
+# @uipath/project-executor
+
+The common run/debug contract that every UiPath project type implements, so a
+caller can run a project without knowing what kind of project it is.
+
+Today each project type ships its own run/debug command with its own arguments,
+its own result shape and its own status vocabulary:
+
+| project type | command | model | status words |
+|---|---|---|---|
+| ProcessOrchestration (BPMN) | `uip maestro bpmn debug` | Studio Web upload → Orchestrator debug session → PIMS instance | `Completed`, `Faulted`, `Cancelled` |
+| Flow | `uip maestro flow debug` | same | same |
+| CaseManagement | `uip maestro case debug` | same | same |
+| Agent | `uip agent debug` | serverless job, polled via Orchestrator Jobs | `Successful`, `Faulted`, `Stopped`, `Suspended` |
+| API Workflow | `uip api-workflow run` | local, in-process | `Successful`, `Faulted` |
+| RPA | external Studio backend | local or remote robot | its own set |
+
+This package holds the types and interfaces those implementations share, so a
+caller (for example a solution-level run command) can treat them uniformly.
+It contains **no execution logic of its own** — only the contract and the
+lifecycle around a run. Implementations are expected to be thin adapters over
+the run/debug service each tool already owns, so a unified entry point and the
+per-tool command cannot drift.
+
+## What is in here
+
+**The contract**
+
+- `ProjectExecutor` — abstract base each project type extends. Operations
+  default to "not supported", so a type opts into exactly what it can do.
+  `runAsync` is the only operation today; interactive debugging (breakpoints,
+  stepping) is deliberately out of scope. Its `protected
+  resolveDefaultEntryPoint` is the single hook for "what runs when the caller
+  named nothing": the base reads the first entry point declared in
+  `entry-points.json`, and an implementation overrides it to put its own
+  convention first (RPA prefers `project.json`'s `main`). Implementations call it
+  from `runAsync`, so a caller that passed an entry point pays for no file read.
+- `IProjectExecutorFactory` — declares `supportedTypes` and creates an executor.
+- `ExecutorsFactoryRepository` (+ the shared `executorsFactoryRepository`)
+  — maps project types to factories. Same shape and registration semantics as
+  `ToolsFactoryRepository` in `@uipath/solutionpackager-tool-core`: the first
+  factory to claim a type keeps it, re-registering the same factory *class* is a
+  silent no-op (two tools each bundling a copy is normal), and only a different
+  class claiming a taken type warns.
+
+  The shared instance hangs off a `Symbol.for` slot on `globalThis`, for the
+  same reason `toolsFactoryRepository` does: tool bundles **inline** this
+  package (builds externalize only `applicationinsights` plus sibling entry
+  points), so every tool — including one built in a different repo, such as
+  `@uipath/rpa-tool` — ships its own copy of the module. With plain module
+  state each copy would get an independent map and cross-tool registration
+  would silently do nothing.
+- `ExecutorFactoryModule` / `isExecutorFactoryModule` / `EXECUTOR_FACTORY_EXPORT`
+  — the shape of a tool's entry point. See below.
+- `ProjectRunner` — the project-level layer. It owns the lifecycle around one
+  run (resolve the factory for the type, create the executor, invoke it, dispose
+  it) and turns an unregistered type or a throwing implementation into a
+  `RunResult`. It passes options through untouched — resolving a default entry
+  point needs I/O against a per-type layout, so that is the executor's job, not
+  the runner's. Callers compose this instead of
+  touching the registry themselves, the same way `@uipath/solution-packager`
+  builds on `@uipath/project-packager`.
+
+**Normalized results**
+
+- `RunStatus` / `mapRunStatus` — folds the three status vocabularies above onto
+  one enum, so callers switch on one thing and an unrecognized backend status
+  degrades to `Unknown` rather than throwing.
+- `RunResult` / `RunErrorCode` / `RunStep` — a superset of what any one type
+  produces. Identifiers differ per backend (`jobKey` for Orchestrator,
+  `instanceId`/`runId` for PIMS, none for the local executor), so all are
+  optional and only `status` is guaranteed.
+
+**Options**
+
+- `ProjectRunOptions` / `SolutionRunOptions`, `RunConnection`, `RunCallbacks`,
+  `SolutionProjectRef`, `RunTarget`.
+- `RunTarget.Online` is the only implemented target. `Local` exists so the
+  choice is explicit at the call site rather than implied.
+- `IExecutorLogger` — a minimal logging surface, structurally satisfied by
+  `logger` from `@uipath/common`, declared here so this package does not force a
+  logging implementation on consumers.
+
+## Implementing it
+
+A tool exposes its factory from `src/executor-tool.ts`, which the host discovers
+by file path. **A tool supplies a factory; it does not register anything.** The
+module's only export is `createExecutorFactory`, and the host decides when, and
+into which registry, to register what it hands back:
+
+```ts
+// src/executor-tool.ts
+import type { ExecutorFactoryModule } from "@uipath/project-executor";
+import { MyExecutorFactory } from "./executor/my-executor-factory.js";
+
+export const createExecutorFactory: ExecutorFactoryModule["createExecutorFactory"] =
+    () => new MyExecutorFactory();
+```
+
+The host side imports it, checks the shape, and registers:
+
+```ts
+const module = await import(executorToolPath);
+if (!isExecutorFactoryModule(module)) {
+    throw new Error(
+        `${executorToolPath} does not export ${EXECUTOR_FACTORY_EXPORT}()`,
+    );
+}
+executorsFactoryRepository.registerProjectExecutorFactory(
+    module.createExecutorFactory(),
+);
+```
+
+This is the same split Studio Web uses for the packager tools, and it exists
+because the alternative — a module that registers during import, as the older
+`src/packager-tool.ts` convention does — is invisible at the call site and
+order-dependent: a stray `import` anywhere silently changes which project types
+look runnable, and the module cannot be imported without mutating global state,
+which makes it awkward to test. With a factory supplier, a test calls
+`createExecutorFactory()` and registers into its own
+`new ExecutorsFactoryRepository()` instead of the process-wide one.
+
+Two more rules worth knowing before adding a factory:
+
+- **One factory per service, not per CLI verb.** A factory's `supportedTypes`
+  must list only the types its wrapped service actually handles. The `maestro`
+  verb, for instance, owns three project types but has three distinct debug
+  services that validate different project files — claiming all three from one
+  factory would route a project into the wrong validator.
+- **`runAsync` should resolve, not reject, for expected failures.** A faulted
+  run is a `RunResult`, not an exception; reject only for programming errors.

package/dist/index.js

@@ -0,0 +1,252 @@
+// src/models/run-options.ts
+var RunTarget;
+((RunTarget2) => {
+  RunTarget2["Online"] = "Online";
+  RunTarget2["Local"] = "Local";
+})(RunTarget ||= {});
+// src/models/run-status.ts
+var RunStatus;
+((RunStatus2) => {
+  RunStatus2["Pending"] = "Pending";
+  RunStatus2["Running"] = "Running";
+  RunStatus2["Succeeded"] = "Succeeded";
+  RunStatus2["Faulted"] = "Faulted";
+  RunStatus2["Cancelled"] = "Cancelled";
+  RunStatus2["Suspended"] = "Suspended";
+  RunStatus2["Unknown"] = "Unknown";
+})(RunStatus ||= {});
+var TERMINAL_RUN_STATUSES = [
+  "Succeeded" /* Succeeded */,
+  "Faulted" /* Faulted */,
+  "Cancelled" /* Cancelled */
+];
+function isTerminalRunStatus(status) {
+  return TERMINAL_RUN_STATUSES.includes(status);
+}
+var RAW_STATUS_MAP = {
+  completed: "Succeeded" /* Succeeded */,
+  faulted: "Faulted" /* Faulted */,
+  cancelled: "Cancelled" /* Cancelled */,
+  canceled: "Cancelled" /* Cancelled */,
+  failed: "Faulted" /* Faulted */,
+  running: "Running" /* Running */,
+  inprogress: "Running" /* Running */,
+  pending: "Pending" /* Pending */,
+  successful: "Succeeded" /* Succeeded */,
+  stopped: "Cancelled" /* Cancelled */,
+  stopping: "Running" /* Running */,
+  suspended: "Suspended" /* Suspended */,
+  terminating: "Running" /* Running */,
+  new: "Pending" /* Pending */,
+  waitingforresource: "Pending" /* Pending */
+};
+function mapRunStatus(rawStatus) {
+  if (!rawStatus)
+    return "Unknown" /* Unknown */;
+  return RAW_STATUS_MAP[rawStatus.toLowerCase()] ?? "Unknown" /* Unknown */;
+}
+
+// src/models/run-result.ts
+var RunErrorCode;
+((RunErrorCode2) => {
+  RunErrorCode2["None"] = "None";
+  RunErrorCode2["InvalidInput"] = "InvalidInput";
+  RunErrorCode2["UnsupportedProjectType"] = "UnsupportedProjectType";
+  RunErrorCode2["Unauthorized"] = "Unauthorized";
+  RunErrorCode2["PrepareFailed"] = "PrepareFailed";
+  RunErrorCode2["StartFailed"] = "StartFailed";
+  RunErrorCode2["ExecutionFailed"] = "ExecutionFailed";
+  RunErrorCode2["Timeout"] = "Timeout";
+  RunErrorCode2["Cancelled"] = "Cancelled";
+  RunErrorCode2["Unknown"] = "Unknown";
+})(RunErrorCode ||= {});
+
+class RunResult {
+  status;
+  errorCode;
+  rawStatus;
+  message;
+  jobKey;
+  instanceId;
+  runId;
+  traceId;
+  steps;
+  output;
+  url;
+  details;
+  constructor(status, errorCode = "None" /* None */, message) {
+    this.status = status;
+    this.errorCode = errorCode;
+    this.message = message;
+  }
+  get isSuccess() {
+    return this.status === "Succeeded" /* Succeeded */ && this.errorCode === "None" /* None */;
+  }
+  get isTerminal() {
+    return isTerminalRunStatus(this.status);
+  }
+  static succeeded(init = {}) {
+    return Object.assign(new RunResult("Succeeded" /* Succeeded */, "None" /* None */), init);
+  }
+  static failed(errorCode, message, init = {}) {
+    return Object.assign(new RunResult("Faulted" /* Faulted */, errorCode, message), init);
+  }
+}
+// src/services/executor-logger.ts
+var noopExecutorLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {}
+};
+// src/services/executor-tool-module.ts
+var EXECUTOR_FACTORY_EXPORT = "createExecutorFactory";
+function isExecutorFactoryModule(module) {
+  return typeof module === "object" && module !== null && typeof module[EXECUTOR_FACTORY_EXPORT] === "function";
+}
+// src/services/executors-factory-repository.ts
+class ExecutorsFactoryRepository {
+  factoryMap = new Map;
+  onConflict;
+  constructor(onConflict) {
+    this.onConflict = onConflict ?? ((message) => console.warn(message));
+  }
+  registerProjectExecutorFactory(factory) {
+    for (const projectType of factory.supportedTypes) {
+      const existing = this.factoryMap.get(projectType);
+      if (existing) {
+        if (existing.constructor?.name !== factory.constructor?.name) {
+          this.onConflict(`Executor factory conflict for project type '${projectType}': ` + `'${existing.constructor?.name}' already registered, ` + `ignoring '${factory.constructor?.name}'.`);
+        }
+        continue;
+      }
+      this.factoryMap.set(projectType, factory);
+    }
+  }
+  canHandleProject(projectType) {
+    return this.factoryMap.has(projectType);
+  }
+  getProjectExecutorFactory(projectType) {
+    const factory = this.factoryMap.get(projectType);
+    if (!factory) {
+      throw new Error(`No executor is registered for project type '${projectType}'. ` + `Registered types: ${this.registeredTypes.join(", ") || "none"}.`);
+    }
+    return factory;
+  }
+  get registeredTypes() {
+    return [...this.factoryMap.keys()];
+  }
+  reset() {
+    this.factoryMap.clear();
+  }
+}
+var REGISTRY_KEY = Symbol.for("@uipath/project-executor/executorsFactoryRepository");
+var _global = globalThis;
+if (!_global[REGISTRY_KEY]) {
+  _global[REGISTRY_KEY] = new ExecutorsFactoryRepository;
+}
+var executorsFactoryRepository = _global[REGISTRY_KEY];
+// src/services/project-executor.ts
+class ProjectExecutor {
+  fileSystem;
+  logger;
+  constructor(fileSystem, logger) {
+    this.fileSystem = fileSystem;
+    this.logger = logger;
+  }
+  runAsync(_options, _cancellationToken) {
+    return Promise.resolve(RunResult.failed("UnsupportedProjectType" /* UnsupportedProjectType */, `${this.constructor.name} does not support run.`));
+  }
+  async resolveDefaultEntryPoint(projectPath) {
+    const entryPointsFile = this.fileSystem.path.join(projectPath, ENTRY_POINTS_FILE_NAME);
+    try {
+      const raw = await this.fileSystem.readFile(entryPointsFile, "utf-8");
+      if (!raw) {
+        return;
+      }
+      const declared = JSON.parse(raw).entryPoints;
+      return this.firstDeclaredEntryPoint(declared);
+    } catch (error) {
+      this.logger.warn(`Could not read the default entry point from ${entryPointsFile}: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+  }
+  asEntryPoint(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+  }
+  firstDeclaredEntryPoint(entryPoints) {
+    if (!Array.isArray(entryPoints)) {
+      return;
+    }
+    for (const entry of entryPoints) {
+      const filePath = this.asEntryPoint(entry?.filePath);
+      if (filePath) {
+        return filePath;
+      }
+    }
+    return;
+  }
+  dispose() {
+    return Promise.resolve();
+  }
+}
+var ENTRY_POINTS_FILE_NAME = "entry-points.json";
+// src/services/project-runner.ts
+class ProjectRunner {
+  fileSystem;
+  logger;
+  registry;
+  constructor(deps) {
+    this.fileSystem = deps.fileSystem;
+    this.logger = deps.logger ?? noopExecutorLogger;
+    this.registry = deps.registry ?? executorsFactoryRepository;
+  }
+  canRun(projectType) {
+    return this.registry.canHandleProject(projectType);
+  }
+  get runnableTypes() {
+    return this.registry.registeredTypes;
+  }
+  async runAsync(options, cancellationToken) {
+    const { projectType, name } = options.project;
+    if (!this.canRun(projectType)) {
+      const known = this.runnableTypes.join(", ") || "none";
+      return RunResult.failed("UnsupportedProjectType" /* UnsupportedProjectType */, `No executor is registered for project type '${projectType}' ` + `(project '${name}'). Runnable types: ${known}.`);
+    }
+    let executor;
+    try {
+      const factory = this.registry.getProjectExecutorFactory(projectType);
+      executor = await factory.createAsync(this.logger, this.fileSystem);
+      this.logger.info(`Running ${name} (${projectType}) on ${options.target}.`);
+      return await executor.runAsync(options, cancellationToken);
+    } catch (error) {
+      return RunResult.failed("Unknown" /* Unknown */, messageOf(error));
+    } finally {
+      try {
+        await executor?.dispose();
+      } catch (error) {
+        this.logger.warn(`Failed to dispose the ${projectType} executor: ${messageOf(error)}`);
+      }
+    }
+  }
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  noopExecutorLogger,
+  mapRunStatus,
+  isTerminalRunStatus,
+  isExecutorFactoryModule,
+  executorsFactoryRepository,
+  TERMINAL_RUN_STATUSES,
+  RunTarget,
+  RunStatus,
+  RunResult,
+  RunErrorCode,
+  ProjectRunner,
+  ProjectExecutor,
+  ExecutorsFactoryRepository,
+  EXECUTOR_FACTORY_EXPORT
+};
+
+//# debugId=F5B1472AD9D0537464756E2164756E21

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+export type { ProjectType } from "./models/project-type";
+export type { ProjectRunOptions, RunCallbacks, RunConnection, SolutionProjectRef, SolutionRunOptions, } from "./models/run-options";
+export { RunTarget } from "./models/run-options";
+export type { RunStep } from "./models/run-result";
+export { RunErrorCode, RunResult } from "./models/run-result";
+export { isTerminalRunStatus, mapRunStatus, RunStatus, TERMINAL_RUN_STATUSES, } from "./models/run-status";
+export type { IProjectExecutorFactory } from "./services/executor-factory";
+export type { IExecutorLogger } from "./services/executor-logger";
+export { noopExecutorLogger } from "./services/executor-logger";
+export type { ExecutorFactoryModule } from "./services/executor-tool-module";
+export { EXECUTOR_FACTORY_EXPORT, isExecutorFactoryModule, } from "./services/executor-tool-module";
+export type { IExecutorsFactoryRepository, IExecutorsFactoryRepositoryConfigurator, } from "./services/executors-factory-repository";
+export { ExecutorsFactoryRepository, executorsFactoryRepository, } from "./services/executors-factory-repository";
+export { ProjectExecutor } from "./services/project-executor";
+export type { ProjectRunnerDeps } from "./services/project-runner";
+export { ProjectRunner } from "./services/project-runner";

package/dist/src/models/project-type.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A project type as it appears in a solution manifest — `Process`, `Agent`,
+ * `processOrchestration`, and whatever a future tool introduces.
+ *
+ * Deliberately a plain string rather than a union with an enum. Manifests are
+ * written by more than one producer with inconsistent casing (solution-sdk
+ * stores `ProcessOrchestration` lower-cased because that is what Studio Web
+ * expects), and a solution may legitimately name a type this package has never
+ * heard of. The alias this replaced — `ProjectTypes | string` from
+ * `@uipath/solutionpackager-tool-core` — collapsed to `string` regardless, so it
+ * validated nothing while making the *run* contract depend on the *packaging*
+ * contract and drag its dependencies along behind it.
+ *
+ * The real contract is elsewhere: an executor declares the exact strings it
+ * claims via `IProjectExecutorFactory.supportedTypes`, and the registry matches
+ * them verbatim. A caller reading a manifest is responsible for handing over the
+ * spelling those executors registered.
+ */
+export type ProjectType = string;

package/dist/src/models/run-options.d.ts

@@ -0,0 +1,149 @@
+import type { ProjectType } from "./project-type";
+import type { RunStep } from "./run-result";
+import type { RunStatus } from "./run-status";
+/**
+ * Where the run executes. Only `Online` is implemented today; the meeting
+ * decision was online (serverless) first, with local/hybrid later, so the
+ * enum exists to keep that choice explicit at the call site rather than
+ * implied.
+ */
+export declare enum RunTarget {
+    /** Serverless execution in the cloud. */
+    Online = "Online",
+    /** Local execution on the developer machine. Not implemented yet. */
+    Local = "Local"
+}
+/** Auth/tenant coordinates a project type needs to reach the backends. */
+export interface RunConnection {
+    baseUrl: string;
+    accessToken: string;
+    organizationId: string;
+    organizationName: string;
+    tenantId?: string;
+    tenantName?: string;
+    /** Orchestrator folder (OrganizationUnitId) the job runs in. */
+    organizationUnitId?: number;
+    folderKey?: string;
+    /**
+     * Fully-qualified Orchestrator folder path, e.g. `Shared/Finance`.
+     *
+     * Some runtimes want the path rather than the id or key — the RPA backend
+     * takes it verbatim — and it cannot be derived from either without a lookup.
+     */
+    folderPath?: string;
+}
+/** Progress callbacks. All optional — a caller may just await the result. */
+export interface RunCallbacks {
+    /** Fired when the normalized status changes. */
+    onStatusChange?: (status: RunStatus, steps?: RunStep[]) => void;
+    /** Fired for log lines emitted by the running project. */
+    onLog?: (message: string) => void;
+}
+/**
+ * A project inside the solution, as seen by the executor layer.
+ *
+ * `designId` is the id from the solution file (`.uipx` `Projects[].Id`);
+ * `cloudProjectId` is the Studio Web project id, which only exists once the
+ * solution has been synced to the cloud.
+ */
+export interface SolutionProjectRef {
+    /** Project name as it appears in the solution. */
+    name: string;
+    projectType: ProjectType;
+    /** Absolute path to the project directory. */
+    projectPath: string;
+    /** Design-time id from the solution file. */
+    designId?: string;
+    /** Studio Web project id, once synced. */
+    cloudProjectId?: string;
+}
+/** Options for running one project. */
+export interface ProjectRunOptions {
+    /** The project to run. */
+    project: SolutionProjectRef;
+    /**
+     * Entry point within the project (e.g. `Main.xaml`, `agent.json`, a
+     * workflow id). When omitted the implementation's default is used.
+     */
+    entryPoint?: string;
+    /** Input arguments passed to the run. */
+    inputArguments?: Record<string, unknown>;
+    target: RunTarget;
+    connection: RunConnection;
+    /** Studio Web solution id, once the solution has been synced. */
+    solutionId?: string;
+    /**
+     * The other projects in the same solution. Implementations that support JIT
+     * resolution use these to let the runtime resolve cross-project calls
+     * without publishing.
+     *
+     * Note for whoever builds the FPS `debug.master` map: Studio Web puts
+     * *every* JIT-enabled project into `processes`, including the lead one
+     * (the lead is identified separately by `debug.master.projectId`). So the
+     * map is built from `[project, ...siblingProjects]`, not from
+     * `siblingProjects` alone.
+     */
+    siblingProjects?: SolutionProjectRef[];
+    /** Milliseconds between status polls. */
+    pollIntervalMs?: number;
+    /** Overall budget for waiting on the run, in milliseconds. */
+    timeoutMs?: number;
+    callbacks?: RunCallbacks;
+    /**
+     * Whether to wait for the run to finish. Defaults to `true` when omitted.
+     *
+     * With `false` the implementation should return as soon as the run has
+     * started, leaving `status` non-terminal (`Pending`/`Running`). It is a real
+     * field rather than a `providerOptions` key because "start it and don't
+     * block" is meaningful for every project type, not one of them.
+     *
+     * Honouring it is best-effort: some backends only expose a blocking call
+     * (a local RPA run through Studio/Helm, for one), so an implementation that
+     * cannot start-without-waiting still returns a normal terminal `RunResult`
+     * rather than failing. Callers must therefore read {@link RunResult.isTerminal}
+     * instead of inferring the outcome from having passed `wait: false`.
+     */
+    wait?: boolean;
+    /**
+     * Run knobs that belong to one project type rather than to every type.
+     * Keys are owned and interpreted by the implementing executor.
+     *
+     * The escape hatch exists so type-specific switches do not have to be
+     * promoted into this shared shape one at a time. RPA, for example, has
+     * `logLevel`, `skipBuild`, `profiling` and `profilingMode`; none of those
+     * mean anything to a serverless agent run. It mirrors how
+     * `RunResult.details` already carries type-specific data on the way out.
+     *
+     * A knob that turns out to be genuinely cross-cutting should graduate to a
+     * real field instead of living here forever.
+     */
+    providerOptions?: Record<string, unknown>;
+}
+/** Options for running a whole solution. */
+export interface SolutionRunOptions {
+    /** Path to the solution directory or `.uis`/`.uipx` file. */
+    solutionPath: string;
+    /**
+     * Name or design id of the lead project — the one whose entry point is
+     * executed. Required when the solution has more than one runnable project.
+     */
+    leadProject?: string;
+    entryPoint?: string;
+    inputArguments?: Record<string, unknown>;
+    target: RunTarget;
+    connection: RunConnection;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    callbacks?: RunCallbacks;
+    /**
+     * When false, return as soon as the run starts instead of awaiting it.
+     * Forwarded to the lead project's executor — see
+     * {@link ProjectRunOptions.wait} for what implementations guarantee.
+     */
+    wait?: boolean;
+    /**
+     * Passed through to the lead project's executor. See
+     * {@link ProjectRunOptions.providerOptions}.
+     */
+    providerOptions?: Record<string, unknown>;
+}

package/dist/src/models/run-result.d.ts

@@ -0,0 +1,67 @@
+import { RunStatus } from "./run-status";
+/** Why a run failed, for callers that need to branch without parsing messages. */
+export declare enum RunErrorCode {
+    None = "None",
+    /** The project/solution path or entry point could not be resolved. */
+    InvalidInput = "InvalidInput",
+    /** No executor is registered for the project type. */
+    UnsupportedProjectType = "UnsupportedProjectType",
+    /** Authentication or authorization failed. */
+    Unauthorized = "Unauthorized",
+    /** The pre-run (JIT) preparation step failed. */
+    PrepareFailed = "PrepareFailed",
+    /** The job could not be started. */
+    StartFailed = "StartFailed",
+    /** The run started but ended in a non-success terminal state. */
+    ExecutionFailed = "ExecutionFailed",
+    /** Polling/waiting exceeded the allotted budget. */
+    Timeout = "Timeout",
+    /** Cancelled via the cancellation token. */
+    Cancelled = "Cancelled",
+    /** Anything not covered above. */
+    Unknown = "Unknown"
+}
+/** One execution step reported by a project type, when it exposes them. */
+export interface RunStep {
+    id: string;
+    name?: string;
+    type?: string;
+    status: RunStatus;
+    startedAt?: string;
+    completedAt?: string;
+}
+/**
+ * Result of running a single project.
+ *
+ * Deliberately a superset of what any one project type produces: identifiers
+ * differ per backend (`jobKey` for Orchestrator, `instanceId`/`runId` for
+ * PIMS), so all are optional and only `status` is guaranteed.
+ */
+export declare class RunResult {
+    status: RunStatus;
+    errorCode: RunErrorCode;
+    /** The project type's own status string, preserved for diagnostics. */
+    rawStatus?: string;
+    message?: string;
+    /** Orchestrator job key, when the run went through a job. */
+    jobKey?: string;
+    /** PIMS debug instance id, when the run went through debug-instances. */
+    instanceId?: string;
+    runId?: string;
+    /** Distributed-trace id, when the runtime supplied one. */
+    traceId?: string;
+    /** Per-step detail, when the project type reports it. */
+    steps?: RunStep[];
+    /** Output arguments, when the run produced any. */
+    output?: Record<string, unknown>;
+    /** Deep link to the run in Studio Web / Orchestrator, when known. */
+    url?: string;
+    /** Anything project-type-specific that does not fit above. */
+    details?: Record<string, unknown>;
+    constructor(status: RunStatus, errorCode?: RunErrorCode, message?: string);
+    /** True only for a successfully completed run. */
+    get isSuccess(): boolean;
+    get isTerminal(): boolean;
+    static succeeded(init?: Partial<RunResult>): RunResult;
+    static failed(errorCode: RunErrorCode, message?: string, init?: Partial<RunResult>): RunResult;
+}

package/dist/src/models/run-status.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Normalized terminal/intermediate status for a run across all project types.
+ *
+ * Each project type reports its own vocabulary — PIMS uses
+ * `Completed/Faulted/Cancelled`, Orchestrator uses
+ * `Successful/Faulted/Stopped/Suspended`, the local serverless executor uses
+ * its own — so implementations map onto this set and callers switch on one
+ * thing. `mapRunStatus` covers the values seen across the current tools.
+ */
+export declare enum RunStatus {
+    /** The job/instance has not started executing yet. */
+    Pending = "Pending",
+    /** Executing. */
+    Running = "Running",
+    /** Finished successfully. */
+    Succeeded = "Succeeded",
+    /** Finished with an error. */
+    Faulted = "Faulted",
+    /** Stopped or cancelled before completing. */
+    Cancelled = "Cancelled",
+    /** Parked waiting on external input (e.g. an Action Center task). */
+    Suspended = "Suspended",
+    /** Reported a status this layer does not recognize — see `rawStatus`. */
+    Unknown = "Unknown"
+}
+/** Statuses from which no further transition is expected. */
+export declare const TERMINAL_RUN_STATUSES: readonly RunStatus[];
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+/**
+ * Map a project-type-specific status string onto the normalized `RunStatus`.
+ * Unrecognized values become `Unknown` rather than throwing — a new backend
+ * status must not fail a run that otherwise succeeded.
+ */
+export declare function mapRunStatus(rawStatus: string | undefined): RunStatus;

package/dist/src/services/executor-factory.d.ts

@@ -0,0 +1,21 @@
+import type { IFileSystem } from "@uipath/filesystem";
+import type { ProjectType } from "../models/project-type";
+import type { IExecutorLogger } from "./executor-logger";
+import type { ProjectExecutor } from "./project-executor";
+/**
+ * Factory for creating a `ProjectExecutor`.
+ *
+ * Mirrors `IProjectToolFactory` from the packager family: a tool package
+ * exports one of these declaring which project types it handles, and the
+ * registry maps each type to it.
+ */
+export interface IProjectExecutorFactory {
+    /** The project types this factory can run. */
+    readonly supportedTypes: readonly ProjectType[];
+    /**
+     * Create a executor instance.
+     * @param logger - logger for the operation
+     * @param fileSystem - file system instance
+     */
+    createAsync(logger: IExecutorLogger, fileSystem: IFileSystem): Promise<ProjectExecutor>;
+}

package/dist/src/services/executor-logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Minimal logging surface the executor layer needs.
+ *
+ * Structurally satisfied by `logger` from `@uipath/common`, so callers can pass
+ * that directly; declared here so `project-executor` does not force a logging
+ * implementation on consumers and so tests can substitute a spy.
+ */
+export interface IExecutorLogger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Discards everything. Useful as a default and in tests. */
+export declare const noopExecutorLogger: IExecutorLogger;

package/dist/src/services/executor-tool-module.d.ts

@@ -0,0 +1,39 @@
+import type { IProjectExecutorFactory } from "./executor-factory";
+/** The export a tool's `executor-tool.ts` entry point must provide. */
+export declare const EXECUTOR_FACTORY_EXPORT = "createExecutorFactory";
+/**
+ * The shape of a tool's `src/executor-tool.ts` entry point.
+ *
+ * A tool **supplies a factory; it does not register anything.** The host imports
+ * the module, calls this, and registers the result into the one shared registry
+ * itself — the same division StudioWeb's `_registerPackagerTools` uses for the
+ * packager factories ("the packager packages no longer self-register on
+ * import").
+ *
+ * Registering on import, or handing the tool the registry to register into,
+ * both put the decision in the wrong place: the host ends up with entries it
+ * never asked for, import order starts to matter, and a stray `import` silently
+ * changes which project types look runnable. Exporting a factory keeps the
+ * tool's job "describe what I can run" and the host's job "decide what is
+ * registered".
+ *
+ * ```ts
+ * // src/executor-tool.ts
+ * import type { ExecutorFactoryModule } from "@uipath/project-executor";
+ * import { MyExecutorFactory } from "./executor/my-executor-factory.js";
+ *
+ * export const createExecutorFactory: ExecutorFactoryModule["createExecutorFactory"] =
+ *     () => new MyExecutorFactory();
+ * ```
+ */
+export interface ExecutorFactoryModule {
+    createExecutorFactory: () => IProjectExecutorFactory;
+}
+/**
+ * Narrow a dynamically imported module to {@link ExecutorFactoryModule}.
+ *
+ * Entry points are resolved by file path and imported dynamically, so the host
+ * has no compile-time guarantee about what came back. Checking here lets it fail
+ * with a message naming the missing export rather than a bare "not a function".
+ */
+export declare function isExecutorFactoryModule(module: unknown): module is ExecutorFactoryModule;

package/dist/src/services/executors-factory-repository.d.ts

@@ -0,0 +1,39 @@
+import type { ProjectType } from "../models/project-type";
+import type { IProjectExecutorFactory } from "./executor-factory";
+/** Registration side of the repository. */
+export interface IExecutorsFactoryRepositoryConfigurator {
+    registerProjectExecutorFactory(factory: IProjectExecutorFactory): void;
+}
+/** Lookup side of the repository. */
+export interface IExecutorsFactoryRepository {
+    /** True when some factory claims this project type. */
+    canHandleProject(projectType: ProjectType): boolean;
+    /**
+     * Get the factory for a project type.
+     * @throws when no factory is registered for the type.
+     */
+    getProjectExecutorFactory(projectType: ProjectType): IProjectExecutorFactory;
+    /** Project types with a registered factory. */
+    readonly registeredTypes: readonly ProjectType[];
+}
+/**
+ * Maps project types to the factory that can run them.
+ *
+ * Deliberately the same shape as `ToolsFactoryRepository` in the packager
+ * family, including the re-registration semantics: a tool package that bundles
+ * its own copy of a factory may register the same type twice, which is a no-op,
+ * while a *different* factory claiming a taken type is a real conflict and
+ * warns rather than silently winning.
+ */
+export declare class ExecutorsFactoryRepository implements IExecutorsFactoryRepository, IExecutorsFactoryRepositoryConfigurator {
+    private readonly factoryMap;
+    private readonly onConflict;
+    constructor(onConflict?: (message: string) => void);
+    registerProjectExecutorFactory(factory: IProjectExecutorFactory): void;
+    canHandleProject(projectType: ProjectType): boolean;
+    getProjectExecutorFactory(projectType: ProjectType): IProjectExecutorFactory;
+    get registeredTypes(): readonly ProjectType[];
+    /** Clear all registrations. Tests only. */
+    reset(): void;
+}
+export declare const executorsFactoryRepository: ExecutorsFactoryRepository;

package/dist/src/services/project-executor.d.ts

@@ -0,0 +1,77 @@
+import type { IFileSystem } from "@uipath/filesystem";
+import type { ProjectRunOptions } from "../models/run-options";
+import { RunResult } from "../models/run-result";
+import type { IExecutorLogger } from "./executor-logger";
+/**
+ * The contract every project type implements so `uip solution run` behaves the
+ * same regardless of what is inside the solution.
+ *
+ * Mirrors `ProjectTool` from the packager family: an abstract base whose
+ * operations default to "not supported", so a project type opts in to exactly
+ * the operations it can do. Today that is `runAsync` only — debug (breakpoints,
+ * stepping) is deliberately out of scope, see docs/solution-run-debug-design.md.
+ *
+ * Implementations are thin adapters over each tool's existing run/debug
+ * service; they should not re-implement execution.
+ */
+export declare abstract class ProjectExecutor {
+    protected readonly fileSystem: IFileSystem;
+    protected readonly logger: IExecutorLogger;
+    constructor(fileSystem: IFileSystem, logger: IExecutorLogger);
+    /**
+     * Run the project and, unless the caller opts out, wait for it to finish.
+     *
+     * Implementations must resolve with a `RunResult` for expected failures
+     * (a faulted run is a result, not an exception) and reject only for
+     * programming errors.
+     */
+    runAsync(_options: ProjectRunOptions, _cancellationToken?: AbortSignal): Promise<RunResult>;
+    /**
+     * The entry point to run when the caller named none.
+     *
+     * The one hook for "what runs by default". The shared implementation returns
+     * the first entry point the project declares in `entry-points.json` — the
+     * same file, shape and "first one wins" rule the packager uses to report a
+     * packaged project's entry point, so a project runs the workflow it publishes
+     * as its own.
+     *
+     * `protected`, and called by an implementation's own `runAsync` rather than
+     * by `ProjectRunner`. Two reasons: resolving a real default needs I/O against
+     * a layout only the project type understands, and only `runAsync` knows
+     * whether it needs one at all — a caller that passed an entry point should
+     * not pay for a file read. It also keeps one method where there were nearly
+     * two: a synchronous `defaultEntryPoint()` could only ever answer for a fixed
+     * name, so every project type whose default lives in a file had to leave it
+     * returning `undefined` and do the real work elsewhere.
+     *
+     * Override to put a project type's own convention first and delegate here for
+     * the rest — the RPA executor prefers `project.json`'s `main` and falls back
+     * to this. Best-effort by contract: a missing or malformed file resolves to
+     * `undefined` rather than failing a run the caller may have given an explicit
+     * entry point for.
+     *
+     * @param projectPath Absolute path to the project directory.
+     */
+    protected resolveDefaultEntryPoint(projectPath: string): Promise<string | undefined>;
+    /**
+     * A declared entry-point path, when it is a usable one.
+     *
+     * `private`: it belongs to the default discovery below, not to the contract
+     * and not to overrides. A project type reading a field of its own vets it
+     * against its own rules.
+     */
+    private asEntryPoint;
+    /**
+     * The first usable `filePath` in `entry-points.json`'s list.
+     *
+     * Scans rather than indexing `[0]` so one malformed element does not hide the
+     * rest of a list that does name a workflow.
+     *
+     * `private` for the same reason as {@link asEntryPoint}: this is how the
+     * default discovery reads *this* file. A project type with a list of its own
+     * elsewhere reads that itself.
+     */
+    private firstDeclaredEntryPoint;
+    /** Release resources. Override when the implementation holds any. */
+    dispose(): Promise<void>;
+}

package/dist/src/services/project-runner.d.ts

@@ -0,0 +1,42 @@
+import type { IFileSystem } from "@uipath/filesystem";
+import type { ProjectType } from "../models/project-type";
+import type { ProjectRunOptions } from "../models/run-options";
+import { RunResult } from "../models/run-result";
+import type { IExecutorLogger } from "./executor-logger";
+import type { IExecutorsFactoryRepository } from "./executors-factory-repository";
+export interface ProjectRunnerDeps {
+    fileSystem: IFileSystem;
+    logger?: IExecutorLogger;
+    /** Defaults to the shared registry. Injectable for tests. */
+    registry?: IExecutorsFactoryRepository;
+}
+/**
+ * Runs a single project by resolving the executor registered for its type.
+ *
+ * This is the project-level layer: it owns the lifecycle around a run — look up
+ * the executor, create it, invoke it, dispose it, and turn an implementation
+ * that throws into a failed `RunResult` — so no caller has to repeat that.
+ *
+ * Callers compose this rather than touching the registry themselves, the same
+ * way `@uipath/solution-packager` builds on `@uipath/project-packager` instead of
+ * reaching for tool factories directly.
+ */
+export declare class ProjectRunner {
+    private readonly fileSystem;
+    private readonly logger;
+    private readonly registry;
+    constructor(deps: ProjectRunnerDeps);
+    /** True when some executor claims this project type. */
+    canRun(projectType: ProjectType): boolean;
+    /** Project types that can be run in this process. */
+    get runnableTypes(): readonly ProjectType[];
+    /**
+     * Run one project to completion.
+     *
+     * Resolves as a failed `RunResult` rather than rejecting for anything the
+     * caller can act on — an unregistered project type, or an executor that
+     * threw instead of returning a result. A caller reporting a run outcome
+     * should not have to also handle exceptions for ordinary failures.
+     */
+    runAsync(options: ProjectRunOptions, cancellationToken?: AbortSignal): Promise<RunResult>;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@uipath/project-executor",
+  "license": "MIT",
+  "version": "1.200.0-preview.118",
+  "description": "Common run contract implemented by every UiPath project type - the shared ProjectExecutor interface behind 'uip solution run'.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/UiPath/cli.git",
+    "directory": "packages/executor/project-executor"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "uipath",
+    "executor",
+    "run",
+    "solution"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@uipath/filesystem": "1.200.0"
+  },
+  "gitHead": "bc87399d98869787498783b3b9383df4426fd896"
+}