@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/services/chore-service.js

@@ -0,0 +1,179 @@
+// Chore domain service. Owns the OData calls under /api/v1/Chores(...) —
+// listing, scheduling toggle, immediate execution, create/update/delete.
+//
+// See docs/ARCHITECTURE.md for the layering.
+import { CHORE_STATUS_UNAVAILABLE, TM1Error, TM1ErrorCode, } from "../../types.js";
+import { classifyChoreExecution } from "./chore-status.js";
+import { rethrowIfSystemic } from "./fallback.js";
+// OData key encoder: double ' per OData literal rules, then percent-encode.
+const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+function frequencyDuration(f) {
+    return `P${f.days}DT${String(f.hours).padStart(2, "0")}H${String(f.minutes).padStart(2, "0")}M${String(f.seconds).padStart(2, "0")}S`;
+}
+export class ChoreService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Connection-scoped verdict on `tm1.ExecuteWithReturn` for chores: null until
+     * the first run has told us, then sticky. Only ever set to false by the
+     * proof described in `execute()` — never by a version guess.
+     */
+    withReturnSupported = null;
+    /**
+     * List all chores with their tasks (process + parameters per step).
+     * GET /api/v1/Chores?$expand=Tasks($expand=Process($select=Name))
+     */
+    async list() {
+        // Expand Process inside Tasks — without it, Task.Process is omitted and the map
+        // below sees undefined for every task.
+        const response = await this.http.request("GET", "/api/v1/Chores?$expand=Tasks($expand=Process($select=Name))");
+        return response.value.map((ch) => ({
+            name: ch.Name,
+            active: ch.Active,
+            startTime: ch.StartTime,
+            frequency: ch.Frequency,
+            processes: (ch.Tasks ?? []).map((t) => ({
+                name: t.Process?.Name ?? "<unknown>",
+                parameters: Object.fromEntries((t.Parameters ?? []).map((p) => [p.Name, p.Value])),
+            })),
+        }));
+    }
+    /**
+     * Activate or deactivate a chore.
+     * PATCH /api/v1/Chores('{name}') with { Active: bool }
+     */
+    async toggleActive(choreName, active) {
+        const path = `/api/v1/Chores('${enc(choreName)}')`;
+        await this.http.request("PATCH", path, { Active: active });
+    }
+    /**
+     * Execute a chore immediately (bypass its schedule), and report how it ended.
+     * opts.timeoutMs overrides the 30s default for chores that run long TI chains.
+     *
+     * Both actions here are SYNCHRONOUS — the POST returns when the chore is
+     * done, which is why the tool exposes a timeout ceiling of an hour. Using
+     * `tm1.ExecuteWithReturn` therefore costs no extra waiting; it only stops us
+     * throwing the status away.
+     *
+     * POST /api/v1/Chores('{name}')/tm1.ExecuteWithReturn?$expand=ErrorLogFile
+     *   — v12 12.5.0 and up. `$expand` is REQUIRED: ErrorLogFile is a navigation
+     *     property on ChoreExecuteResult, so without it the filename is silently
+     *     absent (the same trap as ProcessService.execute).
+     * POST /api/v1/Chores('{name}')/tm1.Execute
+     *   — everywhere else. Returns 204, so no status exists to report.
+     */
+    async execute(choreName, opts) {
+        const plain = `/api/v1/Chores('${enc(choreName)}')/tm1.Execute`;
+        if (this.withReturnSupported === false) {
+            return this.executeWithoutStatus(plain, opts);
+        }
+        const withReturn = `/api/v1/Chores('${enc(choreName)}')/tm1.ExecuteWithReturn?$expand=ErrorLogFile`;
+        try {
+            const response = await this.http.request("POST", withReturn, {}, opts);
+            this.withReturnSupported = true;
+            return classifyChoreExecution(response?.ChoreExecuteStatusCode, response?.ErrorLogFile?.Filename);
+        }
+        catch (error) {
+            rethrowIfSystemic(error);
+            // A build without the action answers 404 — and so does a chore that does
+            // not exist. Measured on 11.8.02900.8: the two differ only in the error
+            // PROSE ("resource can not be resolved on type 'Chore'" vs "can not be
+            // found in collection of type 'Chore'"), and prose is not something this
+            // codebase parses (a v11 server answers in the server's own language).
+            //
+            // So do not classify the 404 — retry on the plain action and let the
+            // outcome say which it was. If the chore was missing, that call 404s the
+            // same way and the error surfaces unchanged, one round-trip later. If it
+            // runs, the chore existed, which proves the 404 was about the action:
+            // record that and stop paying for the probe.
+            //
+            // Nothing can have executed here: a 404 means the request never reached
+            // an action, so the retry cannot double-run the chore.
+            if (error instanceof TM1Error &&
+                error.code === TM1ErrorCode.NOT_FOUND &&
+                this.withReturnSupported === null) {
+                const result = await this.executeWithoutStatus(plain, opts);
+                this.withReturnSupported = false;
+                return result;
+            }
+            throw error;
+        }
+    }
+    /**
+     * The statusless path: run the chore, report that nothing is known about how
+     * it ended. Deliberately NOT `{success: true}` — that claim is what this
+     * whole change exists to remove.
+     */
+    async executeWithoutStatus(path, opts) {
+        await this.http.request("POST", path, {}, opts);
+        return {
+            success: false,
+            outcome: "indeterminate",
+            choreErrorStatus: CHORE_STATUS_UNAVAILABLE,
+            statusUnavailable: true,
+        };
+    }
+    /**
+     * Create a new chore.
+     * POST /api/v1/Chores
+     */
+    async create(chore) {
+        const body = {
+            Name: chore.name,
+            StartTime: chore.startTime,
+            DSTSensitive: chore.dstSensitive,
+            Active: chore.active,
+            ExecutionMode: chore.executionMode,
+            Frequency: frequencyDuration(chore.frequency),
+            Tasks: chore.steps.map((step, idx) => ({
+                Step: idx,
+                "Process@odata.bind": `Processes('${enc(step.process)}')`,
+                Parameters: step.parameters.map((p) => ({
+                    Name: p.name,
+                    Value: p.value,
+                })),
+            })),
+        };
+        await this.http.request("POST", "/api/v1/Chores", body);
+    }
+    /**
+     * Update an existing chore (partial update).
+     * PATCH /api/v1/Chores('{name}')
+     */
+    async update(choreName, updates) {
+        const path = `/api/v1/Chores('${enc(choreName)}')`;
+        const body = {};
+        if (updates.startTime !== undefined)
+            body.StartTime = updates.startTime;
+        if (updates.active !== undefined)
+            body.Active = updates.active;
+        if (updates.dstSensitive !== undefined)
+            body.DSTSensitive = updates.dstSensitive;
+        if (updates.executionMode !== undefined)
+            body.ExecutionMode = updates.executionMode;
+        if (updates.frequency !== undefined) {
+            body.Frequency = frequencyDuration(updates.frequency);
+        }
+        if (updates.steps !== undefined) {
+            body.Tasks = updates.steps.map((step, idx) => ({
+                Step: idx,
+                "Process@odata.bind": `Processes('${enc(step.process)}')`,
+                Parameters: step.parameters.map((p) => ({
+                    Name: p.name,
+                    Value: p.value,
+                })),
+            }));
+        }
+        await this.http.request("PATCH", path, body);
+    }
+    /**
+     * Delete a chore.
+     * DELETE /api/v1/Chores('{name}')
+     */
+    async delete(choreName) {
+        await this.http.request("DELETE", `/api/v1/Chores('${enc(choreName)}')`);
+    }
+}
+//# sourceMappingURL=chore-service.js.map

package/dist/tm1-client/services/chore-status.d.ts

@@ -0,0 +1,11 @@
+import type { ChoreResult } from "../../types.js";
+/**
+ * Turn TM1's `ChoreExecuteStatusCode` into a `ChoreResult`.
+ *
+ * Mirrors `classifyExecution`'s three fail-open guards — absent status is not
+ * success, a non-`CompletedSuccessfully` code is not a flat failure, and an
+ * unrecognised code is never a guess — but over the chore table above, not the
+ * process one.
+ */
+export declare function classifyChoreExecution(statusCode: string | undefined, errorLogFile: string | undefined): ChoreResult;
+//# sourceMappingURL=chore-status.d.ts.map

package/dist/tm1-client/services/chore-status.js

@@ -0,0 +1,127 @@
+// Classification of TM1's `ChoreExecuteStatusCode`.
+//
+// This is NOT `process-status.ts` with different names, and the two must never
+// be merged. A chore reports on a different axis than a process, and the codes
+// that look identical do not mean the same thing. Measured against v12 12.5.9
+// on 2026-08-21, with the identical TI bodies run standalone as a control:
+//
+//   TI body in the step   standalone process        inside a chore
+//   ───────────────────   ───────────────────────   ─────────────────────────────
+//   (clean)               CompletedSuccessfully ✓   CompletedSuccessfully  ✓
+//   ItemReject            CompletedWithMessages ✓   CompletedSuccessfully  ✓
+//   ProcessQuit           QuitCalled            ✓   CompletedWithMessages  ✓
+//   ProcessError          Aborted               ✗   CompletedWithMessages  ✓
+//   CellPutN → no cube    Aborted               ✗   CompletedWithMessages  ✓
+//   ProcessRollback       RollbackCalled        ✗   ProcessRollbackCalled  ✗
+//                                               ↑                          ↑
+//                                    ✓ = the step's writes survived the run
+//
+// Two findings drive everything below, and neither is guessable from the names:
+//
+//  1. A step that ABORTS commits its writes. `ProcessError` and a write into a
+//     missing cube both roll back when the process runs on its own; inside a
+//     chore the marker cell written just before the abort is still there
+//     afterwards, and the chore calls it `CompletedWithMessages`. Mapping
+//     chore statuses through the process table would therefore report
+//     `rolled_back` for a run that committed — the exact fail-open T-4 closed
+//     for processes, reintroduced from the other side.
+//
+//  2. Chores do NOT stop at a failing step. With the failing process as step 1
+//     and a clean writer as step 2, step 2 ran and committed in every case, in
+//     both execution modes. (`tm1_execute_chore` used to tell callers the
+//     opposite.)
+//
+// `ProcessRollbackCalled` is the only status that reports discarded writes, and
+// how much it discards is the one place `ExecutionMode` shows through:
+//   SingleCommit   — everything the chore had written up to that point is gone.
+//   MultipleCommit — only the rolling-back step's own writes are gone.
+// Later steps run and commit under both. Measured in both modes.
+import { CHORE_STATUS_UNKNOWN } from "../../types.js";
+/**
+ * Statuses observed on a run whose writes were COMMITTED.
+ *
+ * `CompletedWithMessages` is what a chore returns for a step that quit AND for
+ * a step that aborted — the two are indistinguishable at chore level, so a
+ * caller who needs to know which step did what has to read the chore log.
+ */
+const COMMITTED_STATUSES = new Set([
+    "CompletedWithMessages",
+]);
+/** Statuses observed on a run whose writes were DISCARDED. */
+const ROLLED_BACK_STATUSES = new Set([
+    "ProcessRollbackCalled",
+]);
+/**
+ * Members of `tm1.ChoreExecuteStatusCode` that the measurement never produced.
+ *
+ * They are declared in v12's `$metadata`, so they are real names, but no TI
+ * exit path drove a chore to any of them: `ProcessQuit` surfaced as
+ * `CompletedWithMessages`, `ProcessError` likewise, `ProcessRollback` as
+ * `ProcessRollbackCalled`. Whether `Aborted`, `RollbackCalled` or a chore-level
+ * `QuitCalled` commit is therefore UNMEASURED, and this file does not guess:
+ * the whole reason the two tables are separate is that the obvious reading —
+ * "Aborted must mean rolled back, it does for processes" — is demonstrably
+ * wrong one line up. They classify as `indeterminate` with that said out loud.
+ */
+const DECLARED_BUT_UNOBSERVED = new Set([
+    "QuitCalled",
+    "Aborted",
+    "RollbackCalled",
+]);
+/**
+ * Turn TM1's `ChoreExecuteStatusCode` into a `ChoreResult`.
+ *
+ * Mirrors `classifyExecution`'s three fail-open guards — absent status is not
+ * success, a non-`CompletedSuccessfully` code is not a flat failure, and an
+ * unrecognised code is never a guess — but over the chore table above, not the
+ * process one.
+ */
+export function classifyChoreExecution(statusCode, errorLogFile) {
+    if (statusCode === undefined || statusCode === "") {
+        return {
+            success: false,
+            outcome: "indeterminate",
+            choreErrorStatus: CHORE_STATUS_UNKNOWN,
+            errorLogFile,
+        };
+    }
+    if (statusCode === "CompletedSuccessfully") {
+        return {
+            success: true,
+            outcome: "succeeded",
+            choreErrorStatus: "CompletedSuccessfully",
+            errorLogFile,
+        };
+    }
+    if (COMMITTED_STATUSES.has(statusCode)) {
+        return {
+            success: false,
+            outcome: "completed_with_errors",
+            choreErrorStatus: statusCode,
+            errorLogFile,
+        };
+    }
+    if (ROLLED_BACK_STATUSES.has(statusCode)) {
+        return {
+            success: false,
+            outcome: "rolled_back",
+            choreErrorStatus: statusCode,
+            errorLogFile,
+        };
+    }
+    if (DECLARED_BUT_UNOBSERVED.has(statusCode)) {
+        return {
+            success: false,
+            outcome: "indeterminate",
+            choreErrorStatus: `${statusCode}: declared in tm1.ChoreExecuteStatusCode but never produced by any measured chore exit path, so whether a chore ending this way commits its writes is unknown. Chore statuses do NOT follow the process ones — a chore step that aborts reports CompletedWithMessages and COMMITS. Verify server state before re-running.`,
+            errorLogFile,
+        };
+    }
+    return {
+        success: false,
+        outcome: "indeterminate",
+        choreErrorStatus: `${statusCode}: unrecognised ChoreExecuteStatusCode — this build does not know whether a chore ending this way commits its changes. Verify server state before re-running.`,
+        errorLogFile,
+    };
+}
+//# sourceMappingURL=chore-status.js.map

package/dist/tm1-client/services/cube-service.d.ts

@@ -0,0 +1,134 @@
+import type { Cube, CubeRules, RuleSyntaxError } from "../../types.js";
+import type { TM1HttpClient } from "../http.js";
+import { type NameFilterOpts, type Paged, type PageOpts } from "./odata-page.js";
+export interface AllRulesOpts {
+    /** Include control cubes (`}`-prefixed). Default false. */
+    includeControl?: boolean;
+    /** Also expand each cube's ordered dimension names into `CubeRules.dimensions`. */
+    withDimensions?: boolean;
+}
+export interface CubeListOpts extends NameFilterOpts {
+    includeRules?: boolean;
+    /** Set to slice server-side. Only legal when every active filter is in NameFilterOpts. */
+    page?: PageOpts;
+}
+export declare class CubeService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * List all cubes with their dimension names.
+     * GET /api/v1/Cubes?$expand=Dimensions($select=Name)
+     *
+     * opts.includeRules adds Rules text to the OData $select so we can derive
+     * hasRules per cube in a single round-trip (no N+1).
+     */
+    list(opts?: {
+        includeRules?: boolean;
+    }): Promise<Cube[]>;
+    /**
+     * Paged variant: with `page` set the slice happens server-side
+     * (`$orderby=Name&$top&$skip&$count=true`) and the return carries the
+     * post-`$filter` total so the caller can build an honest `Page<T>`.
+     * `total` is undefined if the server omitted `@odata.count` — fall back to
+     * an unpaged fetch then.
+     */
+    list(opts: CubeListOpts & {
+        page: PageOpts;
+    }): Promise<Paged<Cube>>;
+    /**
+     * Return ordered dimension-name list of a cube.
+     * GET /api/v1/Cubes('{name}')?$expand=Dimensions($select=Name)
+     */
+    getDimensionNames(cubeName: string): Promise<string[]>;
+    /**
+     * Cheap existence probe: a single GET with $select=Name (404 → false)
+     * instead of list(), which pulls every cube plus its dimensions just to
+     * check one name. Rethrows anything that isn't NOT_FOUND — in particular a
+     * denial, which is "you may not look", not "it is not there".
+     *
+     * Structural on purpose. The alternative — reading existence out of the
+     * error sentence of a failed query — is wrong on any server whose version
+     * or locale words that sentence differently, and TM1 does both.
+     * GET /api/v1/Cubes('{name}')?$select=Name
+     */
+    exists(cubeName: string): Promise<boolean>;
+    /**
+     * Create a new cube with the given dimensions (in order).
+     * POST /api/v1/Cubes
+     */
+    create(name: string, dimensionNames: string[]): Promise<void>;
+    /**
+     * Delete a cube.
+     * DELETE /api/v1/Cubes('{name}')
+     */
+    delete(name: string): Promise<void>;
+    /**
+     * Get the rules text for a cube.
+     * GET /api/v1/Cubes('{name}')/Rules
+     */
+    getRules(cubeName: string): Promise<CubeRules>;
+    /**
+     * Bulk-fetch rules for every cube in a single round trip.
+     * GET /api/v1/Cubes?$select=Name,Rules
+     * Control cubes (Name starts with `}`) excluded unless includeControl=true.
+     *
+     * With `top` set the cap is pushed server-side ($top + $orderby=Name for
+     * stable ordering + $count=true) and the return carries the server-side
+     * total matching the filter so callers can report truncation honestly.
+     *
+     * `withDimensions` adds `$expand=Dimensions($select=Name)` to the same
+     * request. A caller that needs a cube's dimension order per rule — the
+     * feeder audit does — would otherwise issue one getDimensionNames() per
+     * rule-bearing cube. Opt-in, because the callers that only read rules text
+     * should not pay for the expansion.
+     */
+    getAllRules(includeControl?: boolean): Promise<CubeRules[]>;
+    getAllRules(includeControl: boolean, top: number): Promise<{
+        items: CubeRules[];
+        /** Server-side total ($count=true); undefined when the server omitted @odata.count. */
+        total: number | undefined;
+    }>;
+    getAllRules(opts: AllRulesOpts): Promise<CubeRules[]>;
+    /**
+     * Create or replace the rules for a cube.
+     * TM1 11.8 sets rules by PATCHing the Cube entity ({Rules: "...text..."}).
+     * PATCH/POST on /Cubes('{name}')/Rules returns 400 "not supported".
+     *
+     * There is no skipcheck switch to pass: SKIPCHECK is a line inside the rules
+     * text, so it travels in `rulesText` like every other statement.
+     */
+    updateRules(cubeName: string, rulesText: string): Promise<void>;
+    /**
+     * Validate cube rule syntax without applying. Empty array = valid.
+     * POST /api/v1/Cubes('{name}')/tm1.CheckRules with { Rules: "..." }
+     */
+    checkRule(cubeName: string, ruleText: string): Promise<RuleSyntaxError[]>;
+    /**
+     * Clear cube cells.
+     *
+     * A **full** clear runs an ephemeral TI with CubeClearData(). tm1.Clear is
+     * not an alternative on either build: 11.8 and 12.5 both answer
+     * "'tm1.Clear' resource can not be resolved on type 'Cube'" for a cube that
+     * exists, and neither declares a clear action anywhere in $metadata — Cube
+     * carries only Lock and Unlock. CubeClearData() is the only route measured
+     * to work.
+     *
+     * A **partial** clear would need tuple selectors, which only tm1.Clear
+     * offers, so no server reachable here can do one. Callers get
+     * UNSUPPORTED_OPERATION pointing at bedrock `}bedrock.cube.data.clear`
+     * rather than a request that is known to 404.
+     */
+    clear(cubeName: string, dimensions: string[], tuples: string[][]): Promise<void>;
+    /** Same verdict for both versions: no tuple-selective clear on this server. */
+    private partialClearUnsupported;
+    /**
+     * Unload a cube from memory. Forces TM1 to discard the in-memory fed-cell
+     * index and reload from disk on next access. Required for feeder corrections
+     * to take effect — the fed-cell index is cumulative, so changes to existing
+     * feeders only become visible after an unload.
+     * POST /api/v1/Cubes('{cube}')/tm1.Unload
+     */
+    unload(cubeName: string): Promise<void>;
+    private clearViaTI;
+}
+//# sourceMappingURL=cube-service.d.ts.map