@uipath/packager-tool-datafabric 1.204.0 → 1.205.0-preview.258

package/dist/inline/inline-entity-service.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Read and edit the entities of an Entity project on disk — the service behind
+ * `uip df entities <verb> --local`.
+ *
+ * Everything here composes pieces that already exist rather than restating
+ * them: {@link verifyPair} resolves a stub to its resource exactly as pack
+ * does, {@link validateEntity} is the only judge of whether a document is
+ * valid, {@link authorField} owns the field-type vocabulary, and
+ * {@link siblingNamesFor} supplies the solution-wide uniqueness input. The job
+ * of this module is sequencing and I/O, not rules.
+ *
+ * Node-only (filesystem + solution-sdk), so it sits on the `./inline` entry
+ * next to `./init` rather than the browser-safe root.
+ */
+import type { EntityJSON } from "@uipath/entity-modeler/schema";
+import { type AuthoredFieldSpec } from "../schema/author-field.js";
+import { type EntityDiagnostic } from "../schema/validate-entity.js";
+/** Reasons a caller can branch on rather than re-deriving from a message. Only
+ *  the cases a command actually distinguishes get one. */
+export declare const INLINE_ENTITY_ERROR_CODES: {
+    /** No directory at the project path — the caller may want to scaffold. */
+    readonly projectNotFound: "PROJECT_NOT_FOUND";
+    /** The directory is there, but no `.uipx` above it. Scaffolding is wrong. */
+    readonly noParentSolution: "NO_PARENT_SOLUTION";
+    /** The solution holds no entity by that name. */
+    readonly entityNotFound: "ENTITY_NOT_FOUND";
+    /** The entity exists, but the solution only references it — a live
+     *  platform entity, not one authored here. */
+    readonly notLocallyAuthored: "NOT_LOCALLY_AUTHORED";
+};
+export type InlineEntityErrorCode = (typeof INLINE_ENTITY_ERROR_CODES)[keyof typeof INLINE_ENTITY_ERROR_CODES];
+/** A failure the caller caused — a missing project, an entity that is not
+ *  there, an edit aimed at a referenced platform entity. Carries instructions
+ *  so the command layer can hand it straight to `fail()`. */
+export declare class InlineEntityError extends Error {
+    readonly instructions: string;
+    readonly code?: InlineEntityErrorCode | undefined;
+    constructor(message: string, instructions: string, code?: InlineEntityErrorCode | undefined);
+}
+export interface InlineEntityOptions {
+    /** Directory the project name resolves against. Defaults to the process cwd. */
+    cwd?: string;
+}
+/** One entity in a project, as `list` reports it. */
+export interface InlineEntitySummary {
+    name: string;
+    /** Absolute path to the `.entity` stub. */
+    stubFile: string;
+    /** Absolute path to the definition resource, when the pair resolves. */
+    resourceFile?: string;
+    /** False for an entity the solution references rather than owns. */
+    locallyAuthored?: boolean;
+    /** Set when the stub and its resource do not form a valid pair. */
+    problem?: string;
+}
+/** The field edits an `update` applies, mirroring the body
+ *  `uip df entities update` takes so one payload serves both. */
+export interface InlineEntityUpdate {
+    addFields?: AuthoredFieldSpec[];
+    updateFields?: Array<{
+        name: string;
+    } & Partial<AuthoredFieldSpec>>;
+    removeFields?: Array<{
+        name: string;
+    }>;
+    displayName?: string;
+    description?: string;
+}
+interface ResolvedProject {
+    projectDir: string;
+    solutionDir: string;
+}
+/**
+ * The solution root a local command acts within, or a clear refusal.
+ *
+ * Exported because the SCAFFOLD path needs the same base the lookup path
+ * uses. `resolveProjectAsync` finds it and then throws `projectNotFound`,
+ * which is what `create` reads as "scaffold it" — so without this the two
+ * halves of one command resolved the project against different directories
+ * and `create` registered a project no other verb could address.
+ */
+export declare function solutionRootAsync(options?: InlineEntityOptions): Promise<string>;
+export declare function resolveProjectAsync(projectName: string, options?: InlineEntityOptions): Promise<ResolvedProject>;
+/**
+ * The project that owns `entityName`, for callers that did not name one.
+ *
+ * `--project-name` is optional on every verb that addresses an EXISTING
+ * entity, because entity names are solution-wide unique and so the project is
+ * derivable. Searching beats assuming: guessing "project = entity name" would
+ * report "project 'Product' not found" when Product simply lives in Catalog,
+ * which sends the caller after the wrong thing.
+ */
+export declare function resolveOwningProjectAsync(entityName: string, options?: InlineEntityOptions): Promise<{
+    projectName: string;
+    entityName: string;
+    solutionDir: string;
+}>;
+/** List the entities in a project, reporting broken pairs rather than throwing
+ *  — a caller listing wants to see the damage, not just the healthy rows. */
+export declare function inlineEntityListAsync(projectName: string, options?: InlineEntityOptions): Promise<InlineEntitySummary[]>;
+/** One row of a solution-wide listing: a project summary plus its owner. */
+export interface InlineEntitySolutionSummary extends InlineEntitySummary {
+    projectName: string;
+    /** The solution these rows were found under. Callers need it to scope
+     *  follow-up calls: a project name is relative to this, not to cwd. */
+    solutionDir: string;
+    /**
+     * Set when the row stands for a PROJECT that could not be listed at all
+     * rather than for one entity in it — an unreadable directory, or a
+     * directory name the inline commands cannot address. The row exists so a
+     * caller gating on this listing (`validate --local` with no arguments)
+     * sees a project it must not silently pass over; `name` is then the
+     * directory name and there is no entity behind it.
+     */
+    projectProblem?: string;
+}
+/**
+ * Every locally authored entity in the solution, across all Entity projects.
+ *
+ * Backs `uip df entities list --local` with no `--project-name`. Reports
+ * broken pairs rather than throwing, like the per-project listing — a caller
+ * surveying a solution wants the damage visible, not an early exit.
+ */
+export declare function inlineEntityListAllAsync(options?: InlineEntityOptions): Promise<InlineEntitySolutionSummary[]>;
+/** Read one entity's authored document. */
+export declare function inlineEntityGetAsync(projectName: string, entityName: string, options?: InlineEntityOptions): Promise<EntityJSON>;
+export interface InlineEntityValidation {
+    entityName: string;
+    resourceFile?: string;
+    diagnostics: EntityDiagnostic[];
+    /** Set instead of `diagnostics` when the stub↔resource pair itself is broken. */
+    pairProblem?: string;
+}
+/**
+ * Validate one entity, or every entity in the project.
+ *
+ * Same two checks pack runs, in the same order — the pair, then the schema —
+ * so a clean result here means the project will not fail pack on its entities.
+ */
+export declare function inlineEntityValidateAsync(projectName: string, options?: InlineEntityOptions & {
+    entityName?: string;
+}): Promise<InlineEntityValidation[]>;
+/**
+ * Apply field edits to an entity and write it back.
+ *
+ * Validates the resulting document before writing, so a rejected edit leaves
+ * the file exactly as it was. Field-type translation is `authorField`'s;
+ * name and type-pair rules are `validateEntity`'s.
+ */
+export declare function inlineEntityUpdateAsync(projectName: string, entityName: string, update: InlineEntityUpdate, options?: InlineEntityOptions): Promise<{
+    entity: EntityJSON;
+    resourceFile: string;
+}>;
+/**
+ * The document `create --local` writes for a new entity with this
+ * definition — authored and validated, touching nothing on disk.
+ *
+ * `create` used to write an empty entity and then apply the definition as an
+ * update, so anything only this layer rejects failed after the first write
+ * and left an empty entity behind, blocking the retry. Authoring the whole
+ * document up front lets `create` write it once, and a rule added to
+ * `authorField` or `validateEntity` guards the create with no copy in the
+ * command layer. The name's collision checks stay with the write: they need
+ * the solution.
+ */
+export declare function authorNewEntity(entityName: string, definition: Pick<InlineEntityUpdate, "addFields" | "displayName" | "description">): EntityJSON;
+/**
+ * Add an entity to a project that already exists.
+ *
+ * The first entity of a new project comes from `entityInitAsync`, which also
+ * creates the project and registers it in the `.uipx`. This is the second and
+ * later ones: pack already supports many entities per project, and only the
+ * scaffolder was limited to one.
+ */
+export declare function inlineEntityAddAsync(projectName: string, entityName: string, options?: InlineEntityOptions, 
+/** From {@link authorNewEntity}; an empty skeleton when omitted. */
+authored?: EntityJSON): Promise<{
+    entityFile: string;
+    resourceFile: string;
+}>;
+/** What a delete removed. Under `force` either half may be absent, because
+ *  the point of that path is a pair that is already half there. */
+export interface InlineEntityDeletion {
+    stubFile?: string;
+    resourceFile?: string;
+    /** True when the pair did not verify and `force` removed what it found. */
+    forced?: boolean;
+}
+/**
+ * Remove an entity: its stub and its definition resource.
+ *
+ * `force` is for the state that most needs removing — a broken pair. Delete
+ * used to resolve the entity first, which refuses anything `verifyPair`
+ * rejects, so every row `list` reports with a `Problem` was undeletable by
+ * CLI and had to be cleaned up by hand.
+ */
+export declare function inlineEntityDeleteAsync(projectName: string, entityName: string, options?: InlineEntityOptions & {
+    force?: boolean;
+}): Promise<InlineEntityDeletion>;
+/**
+ * Remove a definition resource that no `.entity` stub declares — what an
+ * interrupted create or delete leaves behind. There is no project to name, so
+ * `delete <Name> --local --force` without `--project-name` lands here when the
+ * owner lookup finds none; the resource must still pass every check
+ * `--force` applies to one (inside the solution, a file, unowned, locally
+ * authored).
+ */
+export declare function inlineEntityDeleteOrphanAsync(entityName: string, options?: InlineEntityOptions): Promise<InlineEntityDeletion>;
+export {};

package/dist/inline.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Inline entity authoring — read and edit the entities of an Entity project on
+ * disk. A separate entry (like `./init`) because it needs the filesystem and
+ * solution-sdk, node-only machinery the root module must not pull into browser
+ * bundles.
+ */
+export type { InlineEntityDeletion, InlineEntityErrorCode, InlineEntityOptions, InlineEntitySolutionSummary, InlineEntitySummary, InlineEntityUpdate, InlineEntityValidation, } from "./inline/inline-entity-service.js";
+export { authorNewEntity, INLINE_ENTITY_ERROR_CODES, InlineEntityError, inlineEntityAddAsync, inlineEntityDeleteAsync, inlineEntityDeleteOrphanAsync, inlineEntityGetAsync, inlineEntityListAllAsync, inlineEntityListAsync, inlineEntityUpdateAsync, inlineEntityValidateAsync, resolveOwningProjectAsync, resolveProjectAsync, solutionRootAsync, } from "./inline/inline-entity-service.js";