@uipath/packager-tool-datafabric 1.201.0-preview.134

package/src/init.ts

@@ -0,0 +1,13 @@
+/**
+ * Entity project scaffolding. A separate entry (like `@uipath/flow-tool/init`)
+ * because it needs the filesystem and solution-sdk — node-only machinery the
+ * root module must not pull into browser bundles.
+ */
+
+export type {
+    AutoCreatedSolution,
+    EntityInitOptions,
+    EntityInitResult,
+    EntityProjectRegistration,
+} from "./init/entity-init-service.js";
+export { entityInitAsync } from "./init/entity-init-service.js";

package/src/pack/constants.ts

@@ -0,0 +1,20 @@
+/** The entity stub extension. Its own module so every caller shares one
+ *  literal. */
+export const ENTITY_EXTENSION_CONST = ".entity";
+
+/** Error code on the `ToolResult` when entity validation fails. */
+export const ENTITY_VALIDATION_FAILED = "ENTITY_VALIDATION_FAILED";
+
+/**
+ * Diagnostic codes pack raises about the PROJECT rather than a single entity.
+ * The per-entity codes live with the checks that raise them: pair failures in
+ * `verify-pair.ts` (`PairFailureCode`) and schema failures in
+ * `validate-entity.ts` (`DIAGNOSTIC_CODES`).
+ */
+export const PACK_DIAGNOSTIC_CODES = {
+    /** A main file belonging to another project type sits in an Entity project. */
+    misplacedMainFile: "MISPLACED_MAIN_FILE",
+    /** The project has entities but no parent solution, so their
+     *  solution-relative resource pointers cannot resolve. */
+    noParentSolution: "NO_PARENT_SOLUTION",
+} as const;

package/src/pack/entity-project-tool.ts

@@ -0,0 +1,226 @@
+import {
+    type IProjectPackOptions,
+    type IProjectValidateOptions,
+    ProjectTool,
+    ToolResult,
+} from "@uipath/solutionpackager-tool-core";
+import { validateEntity } from "../schema/validate-entity.js";
+import {
+    ENTITY_EXTENSION_CONST as ENTITY_EXTENSION,
+    ENTITY_VALIDATION_FAILED,
+    PACK_DIAGNOSTIC_CODES,
+} from "./constants.js";
+import { findSolutionRoot, verifyPair } from "./verify-pair.js";
+
+export { ENTITY_VALIDATION_FAILED } from "./constants.js";
+
+/** One pack finding. Codes come from verifyPair, validateEntity, or the
+ *  project-level checks below. */
+export interface EntityPackDiagnostic {
+    file: string;
+    code: string;
+    message: string;
+    fieldName?: string;
+}
+
+/**
+ * Validate-only. Entity projects emit no package — their definition resources
+ * under `resources/solution_folder/entity/native/` are the deployable payload —
+ * so packing means proving every stub↔resource pair is intact and every schema
+ * valid, then returning `packages: []`. Never writes.
+ *
+ * The same checks run behind `validateAsync` and `packAsync`, so solution
+ * validate and solution pack can never disagree.
+ */
+export class EntityProjectTool extends ProjectTool {
+    override async validateAsync(
+        options: IProjectValidateOptions,
+        _cancellationToken?: AbortSignal,
+    ): Promise<ToolResult> {
+        return this.checkProjectAsync(options.projectPath);
+    }
+
+    override async packAsync(
+        options: IProjectPackOptions,
+        _cancellationToken?: AbortSignal,
+    ): Promise<ToolResult> {
+        const result = await this.checkProjectAsync(options.projectPath);
+        if (result.isSuccess) {
+            this.logger.info(
+                "Entity project is valid — no package emitted; the entity resources are the deployable payload.",
+            );
+        }
+        return result;
+    }
+
+    private async checkProjectAsync(projectPath: string): Promise<ToolResult> {
+        const fs = this.fileSystem;
+        const diagnostics: EntityPackDiagnostic[] = [];
+
+        let entries: string[] = [];
+        try {
+            entries = await fs.readdir(projectPath);
+        } catch {
+            return new ToolResult(
+                ENTITY_VALIDATION_FAILED,
+                `Entity project directory '${projectPath}' could not be read.`,
+                [],
+                "Check that the project path in the solution manifest points at an existing directory.",
+            );
+        }
+
+        const stubs = sorted(
+            entries.filter((name) => name.endsWith(ENTITY_EXTENSION)),
+        );
+
+        // A `.flow` inside an Entity project belongs to a Flow project: fail
+        // with move guidance rather than ignore a file the explorer renders.
+        for (const foreign of sorted(
+            entries.filter((name) => name.endsWith(".flow")),
+        )) {
+            diagnostics.push({
+                file: fs.path.join(projectPath, foreign),
+                code: PACK_DIAGNOSTIC_CODES.misplacedMainFile,
+                message: `'${foreign}' is a Flow main file inside an Entity project — move it to a Flow project.`,
+            });
+        }
+
+        const solutionDir = await findSolutionRoot(projectPath, fs);
+        if (solutionDir === undefined) {
+            if (stubs.length > 0) {
+                diagnostics.push({
+                    file: projectPath,
+                    code: PACK_DIAGNOSTIC_CODES.noParentSolution,
+                    message:
+                        "Entity project has no parent solution (.uipx not found) — the stubs' solution-relative resource pointers cannot resolve.",
+                });
+            }
+        } else {
+            diagnostics.push(
+                ...(await this.checkStubsAsync(
+                    projectPath,
+                    solutionDir,
+                    stubs,
+                )),
+            );
+        }
+
+        if (diagnostics.length === 0) {
+            return ToolResult.success();
+        }
+
+        const result = new ToolResult(
+            ENTITY_VALIDATION_FAILED,
+            `Entity validation failed with ${diagnostics.length} issue(s). First: ${diagnostics[0]?.message}`,
+            [],
+            "Fix the listed entities (open them in the entity editor, or restore missing resources) and pack again.",
+        );
+        result.details = { diagnostics };
+        return result;
+    }
+
+    /** Verify every pair and validate each schema it resolves to, in stub
+     *  order. */
+    private async checkStubsAsync(
+        projectPath: string,
+        solutionDir: string,
+        stubs: readonly string[],
+    ): Promise<EntityPackDiagnostic[]> {
+        const fs = this.fileSystem;
+        const diagnostics: EntityPackDiagnostic[] = [];
+        const allEntityNames = await collectSolutionEntityNames(
+            solutionDir,
+            fs,
+        );
+
+        for (const stubName of stubs) {
+            const stubFile = fs.path.join(projectPath, stubName);
+            const pair = await verifyPair(stubFile, solutionDir, fs);
+            if (!pair.ok) {
+                diagnostics.push({
+                    file: stubFile,
+                    code: pair.failure.code,
+                    message: pair.failure.message,
+                });
+                continue;
+            }
+            for (const diagnostic of validateEntity(pair.entity, {
+                siblingNames: withoutOneOccurrence(
+                    allEntityNames,
+                    pair.entityName,
+                ),
+            })) {
+                diagnostics.push({
+                    file: pair.resourceFile,
+                    code: diagnostic.code,
+                    message: diagnostic.message,
+                    fieldName: diagnostic.fieldName,
+                });
+            }
+        }
+        return diagnostics;
+    }
+}
+
+/** Code-unit ordering, stated explicitly: diagnostics come out in this order, so
+ *  it must not shift between environments. `localeCompare` would hand that to
+ *  the runtime's ICU data and default locale. */
+function sorted(names: readonly string[]): string[] {
+    return [...names].sort(compareCodeUnits);
+}
+
+function compareCodeUnits(left: string, right: string): number {
+    if (left < right) {
+        return -1;
+    }
+    return left > right ? 1 : 0;
+}
+
+/** An entity's siblings are every name in the solution except one occurrence of
+ *  its own — names are solution-wide unique. */
+function withoutOneOccurrence(
+    names: readonly string[],
+    name: string,
+): string[] {
+    const siblings = [...names];
+    const self = siblings.indexOf(name);
+    if (self >= 0) {
+        siblings.splice(self, 1);
+    }
+    return siblings;
+}
+
+/** Every entity name in the solution, read from stub filenames one directory
+ *  deep. Duplicates are kept so cross-project collisions surface. */
+async function collectSolutionEntityNames(
+    solutionDir: string,
+    fs: Parameters<typeof findSolutionRoot>[1],
+): Promise<string[]> {
+    const names: string[] = [];
+    let topLevel: string[] = [];
+    try {
+        topLevel = await fs.readdir(solutionDir);
+    } catch {
+        return names;
+    }
+    for (const entry of topLevel) {
+        if (entry === "resources" || entry.startsWith(".")) {
+            continue;
+        }
+        const dir = fs.path.join(solutionDir, entry);
+        try {
+            const stat = await fs.stat(dir);
+            if (!stat?.isDirectory()) {
+                continue;
+            }
+            for (const file of await fs.readdir(dir)) {
+                if (file.endsWith(ENTITY_EXTENSION)) {
+                    names.push(fs.path.basename(file, ENTITY_EXTENSION));
+                }
+            }
+        } catch {
+            /* unreadable entry — skip */
+        }
+    }
+    return names;
+}

package/src/pack/entity-tool-factory.ts

@@ -0,0 +1,26 @@
+import type {
+    IFileSystem,
+    IProjectToolFactory,
+    IToolLogger,
+    ProjectTool,
+    ProjectType,
+} from "@uipath/solutionpackager-tool-core";
+import { EntityProjectTool } from "./entity-project-tool.js";
+
+/**
+ * Factory the packer's registry stores for project type `Entity`. Registered by
+ * `@uipath/data-fabric-tool/packager-tool` (CLI) and at activation by the
+ * Maestro VS Code extension; registering the same factory twice is a no-op.
+ * `"Entity"` is a string `ProjectType` — the tool-core enum is extensible, so
+ * no core change was needed.
+ */
+export class EntityToolFactory implements IProjectToolFactory {
+    readonly supportedTypes: readonly ProjectType[] = ["Entity"];
+
+    async createAsync(
+        logger: IToolLogger,
+        fileSystem: IFileSystem,
+    ): Promise<ProjectTool> {
+        return new EntityProjectTool(fileSystem, logger);
+    }
+}

package/src/pack/verify-pair.ts

@@ -0,0 +1,208 @@
+import type { EntityJSON } from "@uipath/entity-modeler/schema";
+import type { IFileSystem } from "@uipath/solutionpackager-tool-core";
+import {
+    EntityResourceError,
+    unwrapResource,
+} from "../resource/resource-io.js";
+import { ENTITY_EXTENSION_CONST as ENTITY_EXTENSION } from "./constants.js";
+
+/** Why a stub↔resource pair failed. Stable codes: pack output and the editor's
+ *  failure states key on these. */
+export type PairFailureCode =
+    | "StubUnparsable"
+    | "StubFileNameMismatch"
+    | "ResourcePathEscapes"
+    | "ResourceMissing"
+    | "ResourceInvalid"
+    | "NameCoupling";
+
+export interface PairFailure {
+    code: PairFailureCode;
+    message: string;
+}
+
+export type PairResult =
+    | { ok: true; entityName: string; resourceFile: string; entity: EntityJSON }
+    | { ok: false; failure: PairFailure };
+
+/**
+ * Does the stub still point at a real, well-formed resource whose name matches?
+ * Checks the stub parses, its filename equals the entity name, the resolved
+ * resource stays inside the solution (stubs can come from unpacked archives, so
+ * a `../../` pointer must not escape), the resource exists and parses, and its
+ * `Name` couples back to the stub. Reads only.
+ */
+export async function verifyPair(
+    stubFile: string,
+    solutionDir: string,
+    fs: IFileSystem,
+): Promise<PairResult> {
+    const parsedStub = await readStub(stubFile, fs);
+    if ("failure" in parsedStub) {
+        return { ok: false, failure: parsedStub.failure };
+    }
+    const stub = parsedStub.stub;
+
+    const baseName = fs.path.basename(stubFile, ENTITY_EXTENSION);
+    if (baseName !== stub.name) {
+        return fail(
+            "StubFileNameMismatch",
+            `Stub file '${baseName}${ENTITY_EXTENSION}' names entity '${stub.name}' — the filename and the entity name must match.`,
+        );
+    }
+
+    const solutionRoot = fs.path.resolve(solutionDir);
+    const resourceFile = fs.path.resolve(
+        solutionRoot,
+        ...stub.resourcePath.split("/"),
+    );
+    // No IPath.sep, so "inside" means starts with root + a separator.
+    const boundary = resourceFile.charAt(solutionRoot.length);
+    if (
+        !resourceFile.startsWith(solutionRoot) ||
+        (boundary !== "/" && boundary !== "\\")
+    ) {
+        return fail(
+            "ResourcePathEscapes",
+            `'${stub.name}': resourcePath '${stub.resourcePath}' points outside the solution.`,
+        );
+    }
+
+    const parsedResource = await readResource(
+        resourceFile,
+        stub.name,
+        stub.resourcePath,
+        fs,
+    );
+    if ("failure" in parsedResource) {
+        return { ok: false, failure: parsedResource.failure };
+    }
+    const resourceRaw = parsedResource.raw;
+
+    let entity: EntityJSON;
+    try {
+        entity = unwrapResource(resourceRaw);
+    } catch (error) {
+        const detail =
+            error instanceof EntityResourceError ? ` (${error.failure})` : "";
+        return fail(
+            "ResourceInvalid",
+            `'${stub.name}': resource '${stub.resourcePath}' is not a valid entity resource${detail}.`,
+        );
+    }
+
+    if (entity.Name !== stub.name) {
+        return fail(
+            "NameCoupling",
+            `Stub '${stub.name}' points at a resource defining entity '${entity.Name}' — the names must match.`,
+        );
+    }
+
+    return { ok: true, entityName: stub.name, resourceFile, entity };
+}
+
+function fail(code: PairFailureCode, message: string): PairResult {
+    return { ok: false, failure: { code, message } };
+}
+
+interface ParsedStub {
+    name: string;
+    resourcePath: string;
+}
+
+/** Unreadable, unparsable and mis-shaped stubs all collapse to one
+ *  `StubUnparsable` failure. */
+async function readStub(
+    stubFile: string,
+    fs: IFileSystem,
+): Promise<{ stub: ParsedStub } | { failure: PairFailure }> {
+    let parsed: { name?: unknown; resourcePath?: unknown };
+    try {
+        const raw = await fs.readFile(stubFile);
+        if (raw === null) {
+            return failure(
+                "StubUnparsable",
+                `'${stubFile}' could not be read.`,
+            );
+        }
+        parsed = JSON.parse(decode(raw)) as typeof parsed;
+    } catch {
+        return failure("StubUnparsable", `'${stubFile}' is not valid JSON.`);
+    }
+    if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.name !== "string" ||
+        typeof parsed.resourcePath !== "string"
+    ) {
+        return failure(
+            "StubUnparsable",
+            `'${stubFile}' must be an object with string 'name' and 'resourcePath'.`,
+        );
+    }
+    return { stub: { name: parsed.name, resourcePath: parsed.resourcePath } };
+}
+
+/** Missing and corrupt are different failures: the first is fixed by restoring
+ *  the file, the second by editing it. */
+async function readResource(
+    resourceFile: string,
+    entityName: string,
+    resourcePath: string,
+    fs: IFileSystem,
+): Promise<{ raw: unknown } | { failure: PairFailure }> {
+    const missing = failure(
+        "ResourceMissing",
+        `'${entityName}': definition resource '${resourcePath}' is missing. Restore it (check trash/backup) or delete the entity.`,
+    );
+    try {
+        const raw = await fs.readFile(resourceFile);
+        if (raw === null) {
+            return missing;
+        }
+        return { raw: JSON.parse(decode(raw)) };
+    } catch (error) {
+        if (error instanceof SyntaxError) {
+            return failure(
+                "ResourceInvalid",
+                `'${entityName}': resource '${resourcePath}' is not valid JSON.`,
+            );
+        }
+        return missing;
+    }
+}
+
+function decode(raw: string | Uint8Array): string {
+    return typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+}
+
+function failure(
+    code: PairFailureCode,
+    message: string,
+): { failure: PairFailure } {
+    return { failure: { code, message } };
+}
+
+/** The owning solution dir, or undefined when outside any solution. */
+export async function findSolutionRoot(
+    startDir: string,
+    fs: IFileSystem,
+): Promise<string | undefined> {
+    let dir = fs.path.resolve(startDir);
+    for (;;) {
+        let entries: string[] = [];
+        try {
+            entries = await fs.readdir(dir);
+        } catch {
+            entries = [];
+        }
+        if (entries.some((name) => name.endsWith(".uipx"))) {
+            return dir;
+        }
+        const parent = fs.path.dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}

package/src/resource/resource-io.ts

@@ -0,0 +1,142 @@
+import type { EntityJSON } from "@uipath/entity-modeler/schema";
+import {
+    ENTITY_RESOURCE_API_VERSION,
+    ENTITY_RESOURCE_DOC_VERSION,
+    ENTITY_RESOURCE_KIND,
+    ENTITY_RESOURCE_TYPE,
+    SOLUTION_FOLDER,
+    type UnifiedResourceFile,
+} from "./unified-resource-file.js";
+
+/**
+ * Deterministic bytes for everything this library writes: 2-space indent, LF,
+ * trailing newline, property order = construction order. One serializer shared
+ * with the editor in the vsix, so a re-save can't produce phantom diffs.
+ */
+export function serialize(value: object): string {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/** The inner document is stored compact (single line) inside `resourceJson`. */
+export function serializeEntityJson(entity: EntityJSON): string {
+    return JSON.stringify(entity);
+}
+
+/** Why `unwrapResource` failed. The editor maps these onto its "definition is
+ *  corrupted" states; pack reports them as diagnostics. */
+export type ResourceParseFailure =
+    | "NotAnObject"
+    | "MissingResource"
+    | "MissingSpec"
+    | "NotAnEntityResource"
+    | "ResourceJsonUnparsable";
+
+export class EntityResourceError extends Error {
+    constructor(
+        public readonly failure: ResourceParseFailure,
+        message: string,
+    ) {
+        super(message);
+        this.name = "EntityResourceError";
+    }
+}
+
+/**
+ * Wrap a schema into a brand-new resource file. For edits use
+ * {@link updateResourceSchema}, which preserves the existing wrapper.
+ */
+export function wrapEntityJson(entity: EntityJSON): UnifiedResourceFile {
+    return {
+        docVersion: ENTITY_RESOURCE_DOC_VERSION,
+        resource: {
+            name: entity.Name,
+            kind: ENTITY_RESOURCE_KIND,
+            type: ENTITY_RESOURCE_TYPE,
+            apiVersion: ENTITY_RESOURCE_API_VERSION,
+            isOverridable: true,
+            dependencies: [],
+            runtimeDependencies: [],
+            folders: [{ fullyQualifiedName: SOLUTION_FOLDER }],
+            spec: {
+                resourceJson: serializeEntityJson(entity),
+                name: entity.Name,
+                displayName: entity.DisplayName,
+                description: entity.Description,
+            },
+            locks: [],
+            key: entity.Id,
+            files: [],
+        },
+    };
+}
+
+/**
+ * Read the schema back out of a parsed resource file. Throws
+ * {@link EntityResourceError} with a stable failure kind.
+ */
+export function unwrapResource(file: unknown): EntityJSON {
+    if (typeof file !== "object" || file === null || Array.isArray(file)) {
+        throw new EntityResourceError(
+            "NotAnObject",
+            "Resource file is not a JSON object.",
+        );
+    }
+    const resource = (file as UnifiedResourceFile).resource;
+    if (typeof resource !== "object" || resource === null) {
+        throw new EntityResourceError(
+            "MissingResource",
+            "Resource file has no 'resource' object.",
+        );
+    }
+    if (resource.kind !== ENTITY_RESOURCE_KIND) {
+        throw new EntityResourceError(
+            "NotAnEntityResource",
+            `Resource kind is '${String(resource.kind)}', expected '${ENTITY_RESOURCE_KIND}'.`,
+        );
+    }
+    const spec = resource.spec;
+    if (
+        typeof spec !== "object" ||
+        spec === null ||
+        typeof spec.resourceJson !== "string"
+    ) {
+        throw new EntityResourceError(
+            "MissingSpec",
+            "Resource file has no 'spec.resourceJson' string.",
+        );
+    }
+    try {
+        return JSON.parse(spec.resourceJson) as EntityJSON;
+    } catch {
+        throw new EntityResourceError(
+            "ResourceJsonUnparsable",
+            "'spec.resourceJson' is not valid JSON.",
+        );
+    }
+}
+
+/**
+ * Replace the schema inside an existing resource file. Returns a new object for
+ * the caller to persist via {@link serialize}. Wrapper properties this function
+ * doesn't own — including ones other tools added — are preserved, and `key` is
+ * left alone since the entity Id is minted once at creation.
+ */
+export function updateResourceSchema(
+    file: UnifiedResourceFile,
+    entity: EntityJSON,
+): UnifiedResourceFile {
+    return {
+        ...file,
+        resource: {
+            ...file.resource,
+            name: entity.Name,
+            spec: {
+                ...file.resource.spec,
+                resourceJson: serializeEntityJson(entity),
+                name: entity.Name,
+                displayName: entity.DisplayName,
+                description: entity.Description,
+            },
+        },
+    };
+}

package/src/resource/unified-resource-file.ts

@@ -0,0 +1,56 @@
+// The solution resource file that stores an entity definition:
+// `resources/solution_folder/entity/native/<Name>.json`. Every resource kind in
+// a packed solution shares this wrapper; only `spec.resourceJson` (the
+// stringified EntityJSON) is entity-specific.
+//
+// Index signatures throughout, so a round-trip preserves properties other tools
+// may have stamped on the file.
+
+export interface ResourceFolderRef {
+    fullyQualifiedName: string;
+    [extra: string]: unknown;
+}
+
+export interface ResourceSpec {
+    /** The entity definition (EntityJSON), stringified. The single copy. */
+    resourceJson: string;
+    name: string;
+    displayName: string;
+    description: string;
+    [extra: string]: unknown;
+}
+
+export interface SolutionResource {
+    name: string;
+    kind: string;
+    type: string;
+    apiVersion: string;
+    isOverridable: boolean;
+    dependencies: unknown[];
+    runtimeDependencies: unknown[];
+    folders: ResourceFolderRef[];
+    spec: ResourceSpec;
+    locks: unknown[];
+    /** The entity's own Id GUID — reused, never minted here. */
+    key: string;
+    files: unknown[];
+    [extra: string]: unknown;
+}
+
+export interface UnifiedResourceFile {
+    docVersion: string;
+    resource: SolutionResource;
+    [extra: string]: unknown;
+}
+
+export const ENTITY_RESOURCE_KIND = "entity";
+export const ENTITY_RESOURCE_TYPE = "native";
+export const ENTITY_RESOURCE_API_VERSION = "dataservice.uipath.com/v2";
+export const ENTITY_RESOURCE_DOC_VERSION = "1.0.0";
+export const SOLUTION_FOLDER = "solution_folder";
+
+/** Solution-root-relative path of an entity's resource file. One convention
+ *  shared by scaffolding, the editor's pairing and pack. */
+export function entityResourcePath(entityName: string): string {
+    return `resources/${SOLUTION_FOLDER}/entity/native/${entityName}.json`;
+}