@knowttl/mg-axi 0.1.0

package/dist/entra-lifecycle-workflows.js

@@ -0,0 +1,673 @@
+import { AxiError } from "axi-sdk-js";
+// EXT-02 lifecycle-workflows reads: the read-only workflow, workflow
+// template, task definition and tenant-settings first part, the
+// second-part top-level run and user/subject processing-result reads and
+// the third-part task-report reads. See
+// README.md for the supported commands and usage. Operation construction
+// stays beside its command; the shared session owns URLs, credentials,
+// paging, retries and error translation, and the SDK owns TOON rendering.
+// This module only maps flags to session calls and projects rows for
+// compact output.
+//
+// Reviewed against the v1.0 lifecycleworkflowscontainer-list-workflows,
+// workflow-get, lifecycleworkflowscontainer-list-workflowtemplates,
+// workflowtemplate-get, lifecycleworkflowscontainer-list-taskdefinitions,
+// taskdefinition-get, lifecyclemanagementsettings-get, workflow-list-runs,
+// run-get, workflow-list-userprocessingresults, userprocessingresult-get,
+// run-list-subjectprocessingresults, subjectprocessingresult-get,
+// workflow-list-taskreports and task-get operation documentation and the
+// reviewed resource property sets for workflow, workflowTemplate,
+// taskDefinition, lifecycleManagementSettings, run, userProcessingResult,
+// subjectProcessingResult, taskReport and task, on 2026-10-06.
+// Workflow list/show take D/A
+// LifecycleWorkflows-Workflow.ReadBasic.All as the least privileged choice
+// (LifecycleWorkflows-Workflow.Read.All or LifecycleWorkflows.Read.All for
+// richer detail); template and top-level task-definition reads take D/A
+// LifecycleWorkflows.Read.All; run, processing-result and task-report reads
+// take D/A LifecycleWorkflows-Reports.Read.All as the least privileged
+// choice (LifecycleWorkflows.Read.All or LifecycleWorkflows.ReadWrite.All
+// for richer detail). The taskReport-nested task and taskDefinition singles
+// have no operation-level documentation page, so they share the reporting
+// family's Reports.Read.All default; the workflow-tasks task-get page
+// documents LifecycleWorkflows-Workflow.Read.All for its own route and the
+// top-level taskdefinition-get page documents LifecycleWorkflows.Read.All
+// for its own route, and both stay named as richer alternatives on denial.
+// Delegated personal Microsoft accounts are not supported.
+// Delegated callers additionally need Global Reader or Lifecycle Workflows
+// Administrator. The run and user-processing lists document $filter (and
+// $select), so --filter passes through as plain $filter with no $count or
+// ConsistencyLevel contract ($search/$orderby/$expand stay unreviewed and
+// $top/$skip stay server-side paging concerns); run and user-processing
+// singles document $select only. The subject list documents $filter but not
+// $select and the subject get documents $expand only, so subject rows
+// arrive whole and are projected locally with --fields (the template-show
+// pattern); the subject navigation stays out everywhere. Task reports
+// aggregate one task's results within one workflow; the task and
+// taskDefinition navigations return the related objects whole (task
+// arguments and definition parameters ride along as reviewed fields) while
+// taskProcessingResults, the subject link and every $expand stay out.
+// The taskReports list documents $select/$filter (with $orderby/$expand
+// unreviewed); the taskReport get and the taskReport-nested task and
+// taskDefinition singles have no operation-level page (the task-get page
+// covers the workflow-tasks route only and documents no query parameters
+// there), so those three singles arrive whole and are projected locally
+// with --fields (--select is refused before credentials). Processing results
+// are personal data: user and subject defaults carry status and counts
+// only, never the subject link. Deeper execution detail (run-nested and
+// third-level processing results, reprocessed runs, subjects, workflow and
+// template tasks, createdBy, lastModifiedBy, previewScope, executionScope,
+// versions, insights, deleted items, custom task extensions) needs its own
+// sub-read and stays out, as do the summary functions (bracketed start/end
+// arguments outside the session-guard function-binding allowlist).
+// Lifecycle workflows need Microsoft Entra ID Governance or Microsoft Entra
+// Suite (every governed user, not only administrators). No mutation (no
+// workflow create/update/delete/activate/run, no settings update) and no
+// beta.
+// Workflows expose the configured joiner/mover/leaver automations. Only
+// scalar properties carry a reviewed $select contract; tasks, runs,
+// processing results, versions, scopes and createdBy/lastModifiedBy links
+// are navigation properties and stay out (tasks ride expanded by default on
+// the get and are dropped in local projection).
+export const KNOWN_WORKFLOW_FIELDS = [
+    "id",
+    "category",
+    "createdDateTime",
+    "deletedDateTime",
+    "description",
+    "displayName",
+    "executionConditions",
+    "isEnabled",
+    "isSchedulingEnabled",
+    "lastModifiedDateTime",
+    "nextScheduleRunDateTime",
+    "version",
+    "quarantineDetails",
+    "settings",
+];
+// Workflow templates expose the pre-configured Entra scenarios new
+// workflows are built from. The tasks relationship is expanded by default
+// on the wire and is dropped here: template tasks belong to a later slice.
+export const KNOWN_WORKFLOW_TEMPLATE_FIELDS = [
+    "id",
+    "category",
+    "description",
+    "displayName",
+    "executionConditions",
+];
+// Task definitions expose the built-in tasks workflows are constructed
+// from. They carry no relationships.
+export const KNOWN_TASK_DEFINITION_FIELDS = [
+    "id",
+    "category",
+    "continueOnError",
+    "description",
+    "displayName",
+    "parameters",
+    "version",
+];
+// Tenant settings expose the workflow schedule interval and the email and
+// quarantine configuration. They carry no relationships; the update action
+// belongs to no read slice.
+export const KNOWN_LIFECYCLE_SETTINGS_FIELDS = [
+    "workflowScheduleIntervalInHours",
+    "emailSettings",
+    "quarantineConfiguration",
+];
+// Runs expose the execution instances of one workflow. activatedOnScope is
+// a complex scope object (not a reviewed scalar) and the processing-result
+// relationships need their own sub-reads, so neither is projected here.
+// totalTasksCounts keeps the resource documentation's spelling.
+export const KNOWN_RUN_FIELDS = [
+    "id",
+    "completedDateTime",
+    "failedTasksCount",
+    "failedUsersCount",
+    "lastUpdatedDateTime",
+    "processingStatus",
+    "scheduledDateTime",
+    "startedDateTime",
+    "successfulUsersCount",
+    "totalTasksCounts",
+    "totalUsersCount",
+    "totalUnprocessedTasksCount",
+    "workflowExecutionType",
+];
+// User processing results aggregate one user's workflow execution. The
+// subject relationship carries the targeted user identity: it needs
+// $expand, stays off the reviewed set, and is never requested.
+export const KNOWN_USER_PROCESSING_FIELDS = [
+    "id",
+    "completedDateTime",
+    "failedTasksCount",
+    "processingStatus",
+    "scheduledDateTime",
+    "startedDateTime",
+    "totalTasksCount",
+    "totalUnprocessedTasksCount",
+    "workflowExecutionType",
+    "workflowVersion",
+];
+// Subject processing results mirror user results for non-user subjects.
+// subjectType stays (it names the subject kind, not the subject); the
+// workflowSubject-typed subject navigation stays out with $expand.
+export const KNOWN_SUBJECT_PROCESSING_FIELDS = [
+    "id",
+    "completedDateTime",
+    "failedTasksCount",
+    "processingStatus",
+    "scheduledDateTime",
+    "startedDateTime",
+    "subjectType",
+    "totalTasksCount",
+    "totalUnprocessedTasksCount",
+    "workflowExecutionType",
+    "workflowVersion",
+];
+// Task reports aggregate one workflow task's processing results within one
+// run. runId names the owning run; the task, taskDefinition and
+// taskProcessingResults relationships need their own sub-reads ($expand
+// stays out), so only scalar report properties are reviewed here.
+export const KNOWN_TASK_REPORT_FIELDS = [
+    "id",
+    "runId",
+    "processingStatus",
+    "successfulUsersCount",
+    "failedUsersCount",
+    "unprocessedUsersCount",
+    "totalUsersCount",
+    "startedDateTime",
+    "completedDateTime",
+    "lastUpdatedDateTime",
+];
+// Tasks are the actions a workflow executes when triggered. arguments
+// carries the configured key/value pairs (for example group IDs); the
+// taskProcessingResults relationship needs its own sub-read, so it stays
+// out with $expand.
+export const KNOWN_TASK_FIELDS = [
+    "id",
+    "arguments",
+    "category",
+    "continueOnError",
+    "description",
+    "displayName",
+    "executionSequence",
+    "isEnabled",
+    "taskDefinitionId",
+];
+const WORKFLOW_KNOWN = new Set(KNOWN_WORKFLOW_FIELDS);
+const WORKFLOW_TEMPLATE_KNOWN = new Set(KNOWN_WORKFLOW_TEMPLATE_FIELDS);
+const TASK_DEFINITION_KNOWN = new Set(KNOWN_TASK_DEFINITION_FIELDS);
+const LIFECYCLE_SETTINGS_KNOWN = new Set(KNOWN_LIFECYCLE_SETTINGS_FIELDS);
+const RUN_KNOWN = new Set(KNOWN_RUN_FIELDS);
+const USER_PROCESSING_KNOWN = new Set(KNOWN_USER_PROCESSING_FIELDS);
+const SUBJECT_PROCESSING_KNOWN = new Set(KNOWN_SUBJECT_PROCESSING_FIELDS);
+const TASK_REPORT_KNOWN = new Set(KNOWN_TASK_REPORT_FIELDS);
+const TASK_KNOWN = new Set(KNOWN_TASK_FIELDS);
+// Compact rows: identifiers plus category and enablement state.
+const DEFAULT_WORKFLOW_LIST_SELECT = ["id", "displayName", "category", "isEnabled", "isSchedulingEnabled"];
+const DEFAULT_WORKFLOW_SHOW_SELECT = [...KNOWN_WORKFLOW_FIELDS];
+const DEFAULT_WORKFLOW_TEMPLATE_LIST_SELECT = ["id", "displayName", "category"];
+const DEFAULT_WORKFLOW_TEMPLATE_SHOW_SELECT = [...KNOWN_WORKFLOW_TEMPLATE_FIELDS];
+const DEFAULT_TASK_DEFINITION_LIST_SELECT = ["id", "displayName", "category", "version"];
+const DEFAULT_TASK_DEFINITION_SHOW_SELECT = [...KNOWN_TASK_DEFINITION_FIELDS];
+const DEFAULT_LIFECYCLE_SETTINGS_SELECT = [...KNOWN_LIFECYCLE_SETTINGS_FIELDS];
+// Compact run rows: identifiers plus execution status and user counts.
+const DEFAULT_RUN_LIST_SELECT = ["id", "processingStatus", "totalUsersCount", "failedUsersCount", "successfulUsersCount"];
+const DEFAULT_RUN_SHOW_SELECT = [...KNOWN_RUN_FIELDS];
+// Processing results are personal data: minimal default fields (status and
+// counts only) on both lists and singles; datetimes and versions need an
+// explicit --select (user results) or --fields (subject results).
+const DEFAULT_USER_PROCESSING_LIST_SELECT = ["id", "processingStatus", "failedTasksCount", "totalTasksCount", "totalUnprocessedTasksCount"];
+const DEFAULT_USER_PROCESSING_SHOW_SELECT = [...DEFAULT_USER_PROCESSING_LIST_SELECT];
+const DEFAULT_SUBJECT_PROCESSING_FIELDS = ["id", "subjectType", "processingStatus", "failedTasksCount", "totalTasksCount", "totalUnprocessedTasksCount"];
+// Compact task-report rows: identifiers plus the owning run and user counts.
+const DEFAULT_TASK_REPORT_LIST_SELECT = ["id", "runId", "processingStatus", "totalUsersCount", "failedUsersCount", "successfulUsersCount"];
+const DEFAULT_TASK_REPORT_SHOW_SELECT = [...KNOWN_TASK_REPORT_FIELDS];
+const DEFAULT_TASK_SHOW_SELECT = [...KNOWN_TASK_FIELDS];
+export const DEFAULT_WORKFLOW_SCOPES = ["https://graph.microsoft.com/LifecycleWorkflows-Workflow.ReadBasic.All"];
+export const DEFAULT_LIFECYCLE_SCOPES = ["https://graph.microsoft.com/LifecycleWorkflows.Read.All"];
+export const DEFAULT_REPORTS_SCOPES = ["https://graph.microsoft.com/LifecycleWorkflows-Reports.Read.All"];
+const TRUNCATE_AT = 500;
+function fieldList(raw, flag, known, knownList, help) {
+    const parts = String(raw)
+        .split(",")
+        .map(part => part.trim())
+        .filter(part => part.length > 0);
+    if (!parts.length)
+        throw new AxiError(`--${flag} needs at least one property`, "VALIDATION_ERROR", [help]);
+    const fields = [];
+    for (const part of parts) {
+        if (!known.has(part)) {
+            throw new AxiError(`Unknown property ${part} in --${flag}`, "VALIDATION_ERROR", [
+                help,
+                `Known properties: ${knownList.join(", ")}`,
+            ]);
+        }
+        if (!fields.includes(part))
+            fields.push(part);
+    }
+    return fields;
+}
+function scopesFor(flags, profile, defaults, help) {
+    if (profile.mode === "application") {
+        if (flags.scopes !== undefined) {
+            throw new AxiError("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", [help, "mg-axi profile show --profile <name>"]);
+        }
+        return undefined;
+    }
+    if (flags.scopes === undefined)
+        return [...defaults];
+    const scopes = String(flags.scopes)
+        .split(",")
+        .map(scope => scope.trim())
+        .filter(scope => scope.length > 0);
+    return scopes;
+}
+function truncateValue(value, full) {
+    if (full)
+        return { value, truncated: false };
+    if (typeof value === "string" && value.length > TRUNCATE_AT) {
+        return { value: `${value.slice(0, TRUNCATE_AT)}... (truncated, ${value.length} chars total)`, truncated: true };
+    }
+    if (Array.isArray(value)) {
+        const results = value.map(item => truncateValue(item, full));
+        return { value: results.map(result => result.value), truncated: results.some(result => result.truncated) };
+    }
+    if (value !== null && typeof value === "object") {
+        let truncated = false;
+        const entries = Object.entries(value).map(([key, item]) => {
+            const result = truncateValue(item, full);
+            truncated = truncated || result.truncated;
+            return [key, result.value];
+        });
+        return { value: Object.fromEntries(entries), truncated };
+    }
+    return { value, truncated: false };
+}
+// Local projection preserves Graph's null/missing distinction: an explicit
+// null stays null, an absent property stays absent and is never synthesized.
+function project(row, fields, full) {
+    const source = row !== null && typeof row === "object" && !Array.isArray(row) ? row : {};
+    const projected = {};
+    let truncated = false;
+    for (const field of fields) {
+        if (!Object.hasOwn(source, field))
+            continue;
+        const result = truncateValue(source[field], full);
+        projected[field] = result.value;
+        truncated = truncated || result.truncated;
+    }
+    return { row: projected, truncated };
+}
+function selectedFields(flags, defaults, known, knownList, help) {
+    const select = flags.select === undefined ? [...defaults] : fieldList(flags.select, "select", known, knownList, help);
+    const fields = flags.fields === undefined ? [...select] : fieldList(flags.fields, "fields", known, knownList, help);
+    const missing = fields.find(field => !select.includes(field));
+    if (missing) {
+        throw new AxiError(`--fields ${missing} was not fetched; request it with --select`, "VALIDATION_ERROR", [help]);
+    }
+    return { select, fields };
+}
+function profileHint(profileName) {
+    return `--profile ${shellValue(profileName)}`;
+}
+function shellValue(value) {
+    return /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function fullHint(command, flags, profileName) {
+    const args = Object.entries({ ...flags, ...(flags.cursor === undefined ? {} : { cursor: "-" }), profile: profileName, full: true })
+        .map(([name, value]) => value === true ? `--${name}` : `--${name} ${shellValue(String(value))}`);
+    return `mg-axi ${command} ${args.join(" ")}`;
+}
+// Denials carry the session's generic grant/role/licence cause;
+// lifecycle workflows adds the scope, roles and licensing that actually
+// unlock these reads, because a 403 alone never says which prerequisite is
+// missing.
+function withGuidance(run, hints = LIFECYCLE_DENIAL_HINTS) {
+    return run().catch(error => {
+        if (error instanceof AxiError && error.code === "GRAPH_ERROR" && /\(403\)/.test(error.message)) {
+            throw new AxiError(error.message, "GRAPH_ERROR", [...hints, ...error.suggestions]);
+        }
+        throw error;
+    });
+}
+const LIFECYCLE_DENIAL_HINTS = [
+    "Lifecycle-workflow reads need LifecycleWorkflows.Read.All plus Global Reader or Lifecycle Workflows Administrator for delegated access, or admin-consented LifecycleWorkflows.Read.All for application access; delegated personal Microsoft accounts are not supported",
+    "Lifecycle workflows need Microsoft Entra ID Governance or Microsoft Entra Suite (every governed user, not only administrators)",
+];
+// Workflow reads document their own least-privileged scope, so denials name
+// ReadBasic first with the richer read alternatives beside it.
+const WORKFLOW_DENIAL_HINTS = [
+    "Workflow reads need LifecycleWorkflows-Workflow.ReadBasic.All (least privileged; LifecycleWorkflows-Workflow.Read.All or LifecycleWorkflows.Read.All for richer detail) plus Global Reader or Lifecycle Workflows Administrator for delegated access, or admin-consented LifecycleWorkflows-Workflow.ReadBasic.All for application access; delegated personal Microsoft accounts are not supported",
+    "Lifecycle workflows need Microsoft Entra ID Governance or Microsoft Entra Suite (every governed user, not only administrators)",
+];
+// Run and processing-result reads document the reports scope, so denials
+// name Reports.Read.All first with the richer read alternatives beside it.
+const REPORTS_DENIAL_HINTS = [
+    "Lifecycle-workflow reporting reads need LifecycleWorkflows-Reports.Read.All (least privileged; LifecycleWorkflows.Read.All or LifecycleWorkflows.ReadWrite.All for richer detail) plus Global Reader or Lifecycle Workflows Administrator for delegated access, or admin-consented LifecycleWorkflows-Reports.Read.All for application access; delegated personal Microsoft accounts are not supported",
+    "Lifecycle workflows need Microsoft Entra ID Governance or Microsoft Entra Suite (every governed user, not only administrators)",
+];
+function workflowId(flags, help) {
+    const workflow = flags.workflow === undefined ? "" : String(flags.workflow);
+    if (!workflow.trim()) {
+        throw new AxiError("--workflow needs the parent lifecycle workflow ID", "VALIDATION_ERROR", [help]);
+    }
+    return workflow;
+}
+function reportId(flags, help) {
+    const report = flags.report === undefined ? "" : String(flags.report);
+    if (!report.trim()) {
+        throw new AxiError("--report needs the parent task report ID", "VALIDATION_ERROR", [help]);
+    }
+    return report;
+}
+const WORKFLOW_LIST = {
+    command: "entra lifecycle workflow list",
+    key: "workflows",
+    known: WORKFLOW_KNOWN,
+    knownList: KNOWN_WORKFLOW_FIELDS,
+    defaultSelect: DEFAULT_WORKFLOW_LIST_SELECT,
+    defaultScopes: DEFAULT_WORKFLOW_SCOPES,
+    hints: WORKFLOW_DENIAL_HINTS,
+    emptyNote: "0 workflows matched; the absence of results is the answer, not an error",
+    standing: profileName => [
+        "Workflows are the configured joiner/mover/leaver automations: a workflow row never carries its tasks, runs or processing results; those belong to later slices",
+        `Show one workflow: mg-axi entra lifecycle workflow show --id <workflow-id> ${profileHint(profileName)}`,
+    ],
+};
+const WORKFLOW_TEMPLATE_LIST = {
+    command: "entra lifecycle workflow-template list",
+    key: "workflowTemplates",
+    known: WORKFLOW_TEMPLATE_KNOWN,
+    knownList: KNOWN_WORKFLOW_TEMPLATE_FIELDS,
+    defaultSelect: DEFAULT_WORKFLOW_TEMPLATE_LIST_SELECT,
+    defaultScopes: DEFAULT_LIFECYCLE_SCOPES,
+    hints: LIFECYCLE_DENIAL_HINTS,
+    emptyNote: "0 workflow templates matched; the absence of results is the answer, not an error",
+    standing: profileName => [
+        "Workflow templates are the pre-configured Entra scenarios new workflows are built from; template tasks belong to a later slice",
+        `Show one workflow template: mg-axi entra lifecycle workflow-template show --id <template-id> ${profileHint(profileName)}`,
+    ],
+};
+const TASK_DEFINITION_LIST = {
+    command: "entra lifecycle task-definition list",
+    key: "taskDefinitions",
+    known: TASK_DEFINITION_KNOWN,
+    knownList: KNOWN_TASK_DEFINITION_FIELDS,
+    defaultSelect: DEFAULT_TASK_DEFINITION_LIST_SELECT,
+    defaultScopes: DEFAULT_LIFECYCLE_SCOPES,
+    hints: LIFECYCLE_DENIAL_HINTS,
+    emptyNote: "0 task definitions matched; the absence of results is the answer, not an error",
+    standing: profileName => [
+        "Task definitions are the built-in tasks workflows are constructed from; they carry no relationships",
+        `Show one task definition: mg-axi entra lifecycle task-definition show --id <task-definition-id> ${profileHint(profileName)}`,
+    ],
+};
+const RUN_LIST = {
+    command: "entra lifecycle run list",
+    key: "runs",
+    known: RUN_KNOWN,
+    knownList: KNOWN_RUN_FIELDS,
+    defaultSelect: DEFAULT_RUN_LIST_SELECT,
+    defaultScopes: DEFAULT_REPORTS_SCOPES,
+    hints: REPORTS_DENIAL_HINTS,
+    emptyNote: "0 runs matched; the absence of results is the answer, not an error",
+    standing: profileName => [
+        "Runs are the execution instances of one workflow: a run row never carries its user, subject or task processing results; those belong to later slices",
+        `Show one run: mg-axi entra lifecycle run show --workflow <workflow-id> --id <run-id> ${profileHint(profileName)}`,
+    ],
+};
+const USER_PROCESSING_LIST = {
+    command: "entra lifecycle user-processing-result list",
+    key: "userProcessingResults",
+    known: USER_PROCESSING_KNOWN,
+    knownList: KNOWN_USER_PROCESSING_FIELDS,
+    defaultSelect: DEFAULT_USER_PROCESSING_LIST_SELECT,
+    defaultScopes: DEFAULT_REPORTS_SCOPES,
+    hints: REPORTS_DENIAL_HINTS,
+    emptyNote: "0 user processing results matched; the absence of results is the answer, not an error",
+    standing: profileName => [
+        "User processing results aggregate one user's workflow execution and carry personal data: defaults stay minimal and the subject link is never requested",
+        `Show one user processing result: mg-axi entra lifecycle user-processing-result show --workflow <workflow-id> --id <result-id> ${profileHint(profileName)}`,
+    ],
+};
+const SUBJECT_PROCESSING_LIST = {
+    command: "entra lifecycle subject-processing-result list",
+    key: "subjectProcessingResults",
+    known: SUBJECT_PROCESSING_KNOWN,
+    knownList: KNOWN_SUBJECT_PROCESSING_FIELDS,
+    defaultSelect: DEFAULT_SUBJECT_PROCESSING_FIELDS,
+    defaultScopes: DEFAULT_REPORTS_SCOPES,
+    hints: REPORTS_DENIAL_HINTS,
+    emptyNote: "0 subject processing results matched; the absence of results is the answer, not an error",
+    queryless: true,
+    standing: profileName => [
+        "Subject processing results mirror user results for non-user subjects and carry personal data: rows arrive whole (Graph documents no $select here) and defaults stay minimal",
+        `Show one subject processing result: mg-axi entra lifecycle subject-processing-result show --workflow <workflow-id> --id <result-id> ${profileHint(profileName)}`,
+    ],
+};
+const TASK_REPORT_LIST = {
+    command: "entra lifecycle task-report list",
+    key: "taskReports",
+    known: TASK_REPORT_KNOWN,
+    knownList: KNOWN_TASK_REPORT_FIELDS,
+    defaultSelect: DEFAULT_TASK_REPORT_LIST_SELECT,
+    defaultScopes: DEFAULT_REPORTS_SCOPES,
+    hints: REPORTS_DENIAL_HINTS,
+    emptyNote: "0 task reports matched; the absence of results is the answer, not an error",
+    standing: profileName => [
+        "Task reports aggregate one workflow task's results within one run: a report row never carries its task, task definition or task processing results; those belong to later slices",
+        `Show one task report: mg-axi entra lifecycle task-report show --workflow <workflow-id> --id <report-id> ${profileHint(profileName)}`,
+    ],
+};
+async function listCollection(shape, session, flags, profile, operation, help, profileName, params = {}, resumeHint) {
+    const cursor = flags.cursor === undefined ? undefined : String(flags.cursor);
+    if (cursor !== undefined && !cursor.trim())
+        throw new AxiError("--cursor needs the opaque cursor from a partial result", "VALIDATION_ERROR", [help]);
+    if (shape.queryless === true && flags.select !== undefined) {
+        throw new AxiError("Graph documents no $select on this read; whole rows are returned and projected locally with --fields", "VALIDATION_ERROR", [help]);
+    }
+    const saved = cursor === undefined ? undefined : session.cursorQuery(operation, cursor);
+    const savedSelect = saved?.$select;
+    const { select, fields } = shape.queryless === true
+        ? { select: [], fields: flags.fields === undefined ? [...shape.defaultSelect] : fieldList(flags.fields, "fields", shape.known, shape.knownList, help) }
+        : selectedFields(flags, savedSelect === undefined ? shape.defaultSelect : fieldList(savedSelect, "select", shape.known, shape.knownList, help), shape.known, shape.knownList, help);
+    const savedFilter = saved?.$filter;
+    const filter = flags.filter === undefined ? savedFilter : String(flags.filter);
+    const scopes = scopesFor(flags, profile, shape.defaultScopes, help);
+    const full = flags.full === true;
+    // These lists document $filter (and $select, except the queryless
+    // subject list), so --filter passes through as plain $filter with no
+    // $count or ConsistencyLevel contract; $search/$orderby/$expand stay
+    // unreviewed and $top/$skip stay server-side paging concerns. Resumed
+    // queries replay the stored $select verbatim so resume never conflicts.
+    // Queryless lists never send $select: rows arrive whole and --fields
+    // projects locally.
+    let sendSelect = [];
+    if (shape.queryless !== true) {
+        sendSelect = cursor === undefined
+            ? select
+            : saved?.$select === undefined ? [] : fieldList(saved.$select, "select", shape.known, shape.knownList, help);
+    }
+    const query = {};
+    if (sendSelect.length)
+        query.$select = sendSelect.join(",");
+    if (filter !== undefined)
+        query.$filter = filter;
+    const args = { profile, operation, params, query, scopes };
+    if (cursor !== undefined)
+        args.cursor = cursor;
+    if (flags.all === true) {
+        if (flags.limit !== undefined)
+            throw new AxiError("--limit and --all cannot be combined", "VALIDATION_ERROR", [help]);
+    }
+    else {
+        args.limit = flags.limit === undefined ? 100 : Number(flags.limit);
+    }
+    const result = await withGuidance(() => session.collect(args), shape.hints);
+    const effectiveFlags = { ...flags, ...(result.query.$select === undefined ? {} : { select: select.join(",") }) };
+    if (result.query.$filter !== undefined)
+        effectiveFlags.filter = result.query.$filter;
+    const rows = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, fields, full);
+        rows.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const truncationHints = truncated ? [fullHint(shape.command, effectiveFlags, profileName)] : [];
+    if (truncated && cursor !== undefined)
+        truncationHints.push("Supply the original input cursor on stdin to replay this result with --full");
+    const resume = resumeHint ?? `Resume losslessly with the same flags plus --cursor - ${profileHint(profileName)} and supply the returned cursor on stdin`;
+    const standing = [...shape.standing(profileName)];
+    if (!result.complete) {
+        return {
+            [shape.key]: rows,
+            count: { returned: rows.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, resume, ...standing],
+        };
+    }
+    const count = { returned: rows.length, complete: true };
+    if (!rows.length) {
+        return { [shape.key]: rows, count, help: [shape.emptyNote, ...standing] };
+    }
+    return { [shape.key]: rows, count, help: [...truncationHints, ...standing] };
+}
+async function showOne(key, command, known, knownList, defaultSelect, defaultScopes, hints, session, flags, profile, operation, help, profileName, params, malformed, queryless = false) {
+    if (queryless && flags.select !== undefined) {
+        throw new AxiError("Graph documents no query parameters on this read; whole rows are always returned", "VALIDATION_ERROR", [help]);
+    }
+    const { select, fields } = queryless
+        ? { select: [...defaultSelect], fields: flags.fields === undefined ? [...defaultSelect] : fieldList(flags.fields, "fields", known, knownList, help) }
+        : selectedFields(flags, defaultSelect, known, knownList, help);
+    const scopes = scopesFor(flags, profile, defaultScopes, help);
+    const full = flags.full === true;
+    // Singles document $select only (the template get documents no query
+    // parameters at all and arrives whole); $expand stays out everywhere:
+    // tasks, createdBy, lastModifiedBy and previewScope belong to later
+    // slices, never to these reads.
+    const query = {};
+    if (!queryless && select.length)
+        query.$select = select.join(",");
+    const raw = await withGuidance(() => session.execute({
+        profile,
+        operation,
+        params,
+        query,
+        scopes,
+    }), hints);
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new AxiError(malformed, "GRAPH_ERROR", [
+            "Single-object reads carry one object; treat anything else as unknown, not empty",
+        ]);
+    }
+    const { row, truncated } = project(raw, fields, full);
+    if (truncated)
+        return { [key]: row, help: [fullHint(command, flags, profileName)] };
+    return { [key]: row };
+}
+async function countCollection(key, emptyNote, defaultScopes, hints, session, flags, profile, operation, help, _profileName, params = {}) {
+    const scopes = scopesFor(flags, profile, defaultScopes, help);
+    // The $count route returns a text/plain integer scalar rather than a
+    // JSON collection, so the leaf reads it through session.execute with
+    // scalar mode and accepts only a non-negative integer. The $count route
+    // carries no operation-level documentation page and takes no
+    // --filter/--select/--limit/--cursor.
+    const raw = await withGuidance(() => session.execute({ profile, operation, params, scopes, scalar: true }), hints);
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        throw new AxiError(`Graph returned a malformed ${key} count body`, "GRAPH_ERROR", [
+            "Counts carry one non-negative integer scalar; treat anything else as unknown, not empty",
+        ]);
+    }
+    const count = { returned: raw, complete: true };
+    return raw === 0 ? { count, help: [emptyNote] } : { count };
+}
+export async function listWorkflows(session, flags, profile, operation, help, profileName) {
+    return listCollection(WORKFLOW_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showWorkflow(session, flags, profile, operation, help, profileName) {
+    return showOne("workflow", "entra lifecycle workflow show", WORKFLOW_KNOWN, KNOWN_WORKFLOW_FIELDS, DEFAULT_WORKFLOW_SHOW_SELECT, DEFAULT_WORKFLOW_SCOPES, WORKFLOW_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": String(flags.id) }, "Graph returned a malformed lifecycle workflow body");
+}
+export async function countWorkflows(session, flags, profile, operation, help, profileName) {
+    return countCollection("workflow", WORKFLOW_LIST.emptyNote, DEFAULT_WORKFLOW_SCOPES, WORKFLOW_DENIAL_HINTS, session, flags, profile, operation, help, profileName);
+}
+export async function listWorkflowTemplates(session, flags, profile, operation, help, profileName) {
+    return listCollection(WORKFLOW_TEMPLATE_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showWorkflowTemplate(session, flags, profile, operation, help, profileName) {
+    return showOne("workflowTemplate", "entra lifecycle workflow-template show", WORKFLOW_TEMPLATE_KNOWN, KNOWN_WORKFLOW_TEMPLATE_FIELDS, DEFAULT_WORKFLOW_TEMPLATE_SHOW_SELECT, DEFAULT_LIFECYCLE_SCOPES, LIFECYCLE_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflowTemplate-id": String(flags.id) }, "Graph returned a malformed workflow template body", true);
+}
+export async function countWorkflowTemplates(session, flags, profile, operation, help, profileName) {
+    return countCollection("workflow template", WORKFLOW_TEMPLATE_LIST.emptyNote, DEFAULT_LIFECYCLE_SCOPES, LIFECYCLE_DENIAL_HINTS, session, flags, profile, operation, help, profileName);
+}
+export async function listTaskDefinitions(session, flags, profile, operation, help, profileName) {
+    return listCollection(TASK_DEFINITION_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showTaskDefinition(session, flags, profile, operation, help, profileName) {
+    return showOne("taskDefinition", "entra lifecycle task-definition show", TASK_DEFINITION_KNOWN, KNOWN_TASK_DEFINITION_FIELDS, DEFAULT_TASK_DEFINITION_SHOW_SELECT, DEFAULT_LIFECYCLE_SCOPES, LIFECYCLE_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "taskDefinition-id": String(flags.id) }, "Graph returned a malformed task definition body");
+}
+export async function countTaskDefinitions(session, flags, profile, operation, help, profileName) {
+    return countCollection("task definition", TASK_DEFINITION_LIST.emptyNote, DEFAULT_LIFECYCLE_SCOPES, LIFECYCLE_DENIAL_HINTS, session, flags, profile, operation, help, profileName);
+}
+export async function showLifecycleSettings(session, flags, profile, operation, help, profileName) {
+    return showOne("settings", "entra lifecycle settings show", LIFECYCLE_SETTINGS_KNOWN, KNOWN_LIFECYCLE_SETTINGS_FIELDS, DEFAULT_LIFECYCLE_SETTINGS_SELECT, DEFAULT_LIFECYCLE_SCOPES, LIFECYCLE_DENIAL_HINTS, session, flags, profile, operation, help, profileName, {}, "Graph returned a malformed lifecycle settings body");
+}
+export async function listRuns(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return listCollection(RUN_LIST, session, flags, profile, operation, help, profileName, { "workflow-id": workflow }, `Resume losslessly with the same --workflow and flags plus --cursor - ${profileHint(profileName)} and supply the returned cursor on stdin`);
+}
+export async function showRun(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return showOne("run", "entra lifecycle run show", RUN_KNOWN, KNOWN_RUN_FIELDS, DEFAULT_RUN_SHOW_SELECT, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow, "run-id": String(flags.id) }, "Graph returned a malformed lifecycle run body");
+}
+export async function countRuns(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return countCollection("run", RUN_LIST.emptyNote, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow });
+}
+export async function listUserProcessingResults(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return listCollection(USER_PROCESSING_LIST, session, flags, profile, operation, help, profileName, { "workflow-id": workflow }, `Resume losslessly with the same --workflow and flags plus --cursor - ${profileHint(profileName)} and supply the returned cursor on stdin`);
+}
+export async function showUserProcessingResult(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return showOne("userProcessingResult", "entra lifecycle user-processing-result show", USER_PROCESSING_KNOWN, KNOWN_USER_PROCESSING_FIELDS, DEFAULT_USER_PROCESSING_SHOW_SELECT, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow, "userProcessingResult-id": String(flags.id) }, "Graph returned a malformed user processing result body");
+}
+export async function countUserProcessingResults(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return countCollection("user processing result", USER_PROCESSING_LIST.emptyNote, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow });
+}
+export async function listSubjectProcessingResults(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return listCollection(SUBJECT_PROCESSING_LIST, session, flags, profile, operation, help, profileName, { "workflow-id": workflow }, `Resume losslessly with the same --workflow and flags plus --cursor - ${profileHint(profileName)} and supply the returned cursor on stdin`);
+}
+export async function showSubjectProcessingResult(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return showOne("subjectProcessingResult", "entra lifecycle subject-processing-result show", SUBJECT_PROCESSING_KNOWN, KNOWN_SUBJECT_PROCESSING_FIELDS, DEFAULT_SUBJECT_PROCESSING_FIELDS, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow, "subjectProcessingResult-id": String(flags.id) }, "Graph returned a malformed subject processing result body", true);
+}
+export async function countSubjectProcessingResults(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return countCollection("subject processing result", SUBJECT_PROCESSING_LIST.emptyNote, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow });
+}
+export async function listTaskReports(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return listCollection(TASK_REPORT_LIST, session, flags, profile, operation, help, profileName, { "workflow-id": workflow }, `Resume losslessly with the same --workflow and flags plus --cursor - ${profileHint(profileName)} and supply the returned cursor on stdin`);
+}
+export async function showTaskReport(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return showOne("taskReport", "entra lifecycle task-report show", TASK_REPORT_KNOWN, KNOWN_TASK_REPORT_FIELDS, DEFAULT_TASK_REPORT_SHOW_SELECT, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow, "taskReport-id": String(flags.id) }, "Graph returned a malformed task report body", true);
+}
+export async function countTaskReports(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    return countCollection("task report", TASK_REPORT_LIST.emptyNote, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow });
+}
+export async function showTaskReportTask(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    const report = reportId(flags, help);
+    return showOne("task", "entra lifecycle task-report task show", TASK_KNOWN, KNOWN_TASK_FIELDS, DEFAULT_TASK_SHOW_SELECT, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow, "taskReport-id": report }, "Graph returned a malformed lifecycle task body", true);
+}
+export async function showTaskReportTaskDefinition(session, flags, profile, operation, help, profileName) {
+    const workflow = workflowId(flags, help);
+    const report = reportId(flags, help);
+    return showOne("taskDefinition", "entra lifecycle task-report task-definition show", TASK_DEFINITION_KNOWN, KNOWN_TASK_DEFINITION_FIELDS, DEFAULT_TASK_DEFINITION_SHOW_SELECT, DEFAULT_REPORTS_SCOPES, REPORTS_DENIAL_HINTS, session, flags, profile, operation, help, profileName, { "workflow-id": workflow, "taskReport-id": report }, "Graph returned a malformed task definition body", true);
+}