@patimweb/pi-zep 1.0.2 → 1.1.1

package/README.md

@@ -54,6 +54,43 @@ list is rendered server-side, so it only contains the Vorgänge of the project
 the page was rendered for. Posting `formrefresh=true` returns the new
 `<select id="vorgangId">` without saving anything.
 
+### Capacity planning ("Einplanung")
+
+Same `ajax.php`, different page context. The plan page has **no table** — the
+numbers live in an ApexCharts options object inside the snippet:
+
+```js
+var optionschart123 = {"series":[
+  {"name":"Verfügbarkeit [108,80 h]","type":"area","data":[6.4,6.4,0, …]},
+  {"name":"K-10000-00003 (…) [54,40 h]","type":"bar","data":[3.2,3.2,0, …]},
+  {"name":"gesamt [82,40 h]","type":"line","data":[4.8,4.8,0, …]}],
+ "xaxis":{"categories":["Heute","Morgen","19.09.", …]},
+ "title":{"text":"<employee>"},"subtitle":{"text":"17.09.2026-17.10.2026"}}
+```
+
+* Read: `POST ajax.php?…&pageContextId=Einplanung&mgr=MeineEinplanungMgr&mgrId=0&action=filter`
+  with the filter form (`von`, `bis`, `von_bisquicklinkdata`, `projektEinplanung`,
+  `gestapelt`, `ff_projektprojektTyp`, `scale`, `Ausführen`).
+* The object is JavaScript, not JSON: axis locales reference a page global
+  (`"locales":[apex_lang_de]`) and axis/tooltip formatters are real function
+  expressions. Both must be neutralised before `JSON.parse` — `extractChartOptions()`
+  replaces function bodies and bare identifiers with `null`.
+* Series kinds are detected on the name prefix (`Verfügbarkeit`, `gesamt`, else
+  project) and only fall back to the chart type. Project totals are read from the
+  `[54,40 h]` suffix in the series name; the per-day values come from the data array.
+* Write: `POST …&mgr=MeineEinplanungMgr&mgrId=0_0_0_1&action=edit&refresh=1` with
+  `edited=[{p:<projektId>,d:<YYYY-MM-DD>,e:<wert|null>,a:'h'|'%',b:<bemerkung>}]`
+  plus `selected`, `scrollLeft` and `einplanungAuchAnNichtArbeitstagen`. Only the
+  cells the grid marked as *edited* are sent, so a save **merges** into the
+  existing plan instead of replacing it; `e:null` clears a cell.
+* A plan cell is either hours (`a:'h'`) or a percentage of that day's
+  availability (`a:'%'`) — 25 % of a 6,40 h day is 1,60 h, which is how a
+  percentage shows up in the chart.
+* Grid markup: `<td class="pep pepdata at pm <date>" data-datum data-einplanung
+  data-einplanungart data-bemerkung data-stundensatz>`. Rows are the projects
+  (`tr[data-projektid]`), the grid is keyboard driven (digits, `%` suffix,
+  Enter = save, Delete = clear).
+
 ### Response shapes (verified against the live server)
 
 | Outcome | `error` | `javascript` | content |
@@ -87,7 +124,9 @@ Other message texts observed:
 * The save response ships a *calendar* snippet targeting `managerdiv_ProjektzeitMgr`, which must not be mistaken for the week table.
 * The ISO date of a day row is in `id="day_YYYY-MM-DD"` (fallback: the `openMahlzeiten(this, 'YYYY-MM-DD')` onclick, then the weekday + `DD.MM.` label).
 * A day row's label is split across `<div>Do</div><div>17.09.</div>`, so plain `innerText` yields `Do17.09.` while tag-stripping yields `Do 17.09.` — parse the latter.
-* Booking rows have 10 cells (`action, von, bis, Dauer, action, Projekt, Vorgang, Tät., fakturierbar, Bemerkung`); the `class="luecke"` spacer rows in between have 1 and must be skipped; the sum row has 3.
+* The **first booking of a day is rendered inside the day row itself** — its label cell carries `rowspan`, so that row holds 12–13 cells. Further bookings of the same day follow as standalone rows, separated by a `class="luecke"` spacer (1 cell). A parser that only knows standalone rows silently drops the day's first booking and attaches the remaining ones to the *previous* day.
+* Booking columns are therefore read relative to the `von` cell: `von, bis, Dauer, ·, Projekt, Vorgang, Tät., fakturierbar, Bemerkung[, Ort]`.
+* The optional last cell is the `Ort` (place of work). It carries no `data-columnid` of its own and ZEP renders it only when there is something to report; a trailing `*` marks a deviation from the default, and a missing cell means `NULL` (Erste Tätigkeitsstätte).
 
 ## Tools
 
@@ -101,6 +140,8 @@ Other message texts observed:
 | `zep_week` | Week overview: bookings with row id, times, duration, sum, under-booked days |
 | `zep_book` | Create bookings — one block or an `entries` array; `dryRun` supported |
 | `zep_delete` | Delete a booking by row id |
+| `zep_plan` | Capacity planning (Einplanung): planned hours per day and project, availability, utilization |
+| `zep_plan_set` | Write into the Einplanung matrix: hours or percent per project and day, or clear a cell |
 
 ## Usage
 
@@ -138,6 +179,9 @@ form re-render for another project, a booking created and confirmed in the week
 table, then deleted and confirmed gone. A rejected booking (plan hours
 exhausted) and a rejected Tätigkeit were reproduced as well.
 
+The capacity planning was exercised the same day: the Einplanung chart was read
+(read path) and a matrix cell was written and read back (`zep_plan_set`).
+
 What is *not* covered by that test run: a successful password login, because
 that requires the account password. The endpoint, the field names and the
 failure contract (`302 → login.php?…&action=login&msg=1&noch=N`) were verified

package/index.ts

@@ -14,6 +14,8 @@
  *   - zep_week:     read the Projektzeiten week overview
  *   - zep_book:     create bookings (one or several blocks)
  *   - zep_delete:   delete a booking
+ *   - zep_plan:     read the capacity planning (Einplanung / Kapa-Planung)
+ *   - zep_plan_set: write planned hours into the Einplanung matrix
  *
  * Design:
  *   - types.ts                  plain data shapes
@@ -36,6 +38,8 @@ import { ZepProjectsTool } from "./src/tools/zep-projects.ts";
 import { ZepWeekTool } from "./src/tools/zep-week.ts";
 import { ZepBookTool } from "./src/tools/zep-book.ts";
 import { ZepDeleteTool } from "./src/tools/zep-delete.ts";
+import { ZepPlanTool } from "./src/tools/zep-plan.ts";
+import { ZepPlanSetTool } from "./src/tools/zep-plan-set.ts";
 
 export default function (pi: ExtensionAPI) {
   loadConfig();
@@ -49,4 +53,6 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool(ZepWeekTool);
   pi.registerTool(ZepBookTool);
   pi.registerTool(ZepDeleteTool);
+  pi.registerTool(ZepPlanTool);
+  pi.registerTool(ZepPlanSetTool);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-zep",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "ZEP time-tracking for pi coding agent — book project times (Projektzeiten) on zep-online.de over plain HTTP, without the paid ZEP API",
   "keywords": [
     "pi-package",
@@ -15,7 +15,7 @@
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=26.0.0"
+    "node": ">=22.18.0"
   },
   "repository": {
     "type": "git",

package/src/clients/zep-client.ts

@@ -19,7 +19,7 @@
  *   3. The token rotates: every response hands out the next one.
  */
 
-import type { LoginResult, ZepAccount, ZepBookingRequest, ZepFormData, ZepSaveResult, ZepSession, ZepWeek } from "../types.ts";
+import type { LoginResult, ZepAccount, ZepBookingRequest, ZepFormData, ZepPlan, ZepPlanRequest, ZepPlanSaveRequest, ZepSaveResult, ZepSession, ZepWeek } from "../types.ts";
 import {
   detectSessionLoss,
   durationBetween,
@@ -28,6 +28,7 @@ import {
   extractRequestToken,
   extractSnippetAlert,
   parseAjaxEnvelope,
+  parsePlan,
   parseSelect,
   parseWeek,
   pickWeekTableSnippet,
@@ -42,6 +43,22 @@ const SAVE_MGR_ID = "3";
 /** `mgrId` of the read-only Projektzeiten table. */
 const TABLE_MGR_ID = "0";
 
+/** The Projektzeiten page (booking form + week table). */
+const TIME_PAGE = { menu: "ProjektzeitVerwaltungMgr", pageContextId: "Projektzeiten", mgr: "ProjektzeitMgr" };
+/**
+ * The Einplanung page (capacity planning). It is read through its filter form:
+ * `action=filter` answers with the rendered chart, whose options object holds
+ * the planned hours per day and project.
+ */
+const PLAN_PAGE = { menu: "MeineEinplanungVerwaltungMgr", pageContextId: "Einplanung", mgr: "MeineEinplanungMgr" };
+const PLAN_MGR_ID = "0";
+/**
+ * `mgrId` of the Einplanung matrix popup. Saving uses `action=edit&refresh=1`
+ * and the same mgrId - the grid hands over only the cells it marked `edited`,
+ * so a save merges into the existing plan instead of replacing it.
+ */
+const PLAN_SAVE_MGR_ID = "0_0_0_1";
+
 export class ZepError extends Error {
   readonly attemptsLeft?: number;
   constructor(message: string, attemptsLeft?: number) {
@@ -308,14 +325,15 @@ export class ZepClient {
     action: string,
     mgrId: string,
     extra: Record<string, string> = {},
+    page: { pageContextId: string; mgr: string } = TIME_PAGE,
   ): { path: string; query: Record<string, string> } {
     if (!this.clientsessid) throw new ZepError("Not logged in.");
     return {
       path: "/view/ajax.php",
       query: {
         CLIENTSESSID: this.clientsessid,
-        pageContextId: "Projektzeiten",
-        mgr: "ProjektzeitMgr",
+        pageContextId: page.pageContextId,
+        mgr: page.mgr,
         mgrId,
         action,
         ...extra,
@@ -330,14 +348,19 @@ export class ZepClient {
   private async ajax(
     action: string,
     mgrId: string,
-    options: { method?: "GET" | "POST"; extra?: Record<string, string>; form?: Record<string, string> } = {},
+    options: {
+      method?: "GET" | "POST";
+      extra?: Record<string, string>;
+      form?: Record<string, string | ReadonlyArray<string>>;
+      page?: { pageContextId: string; mgr: string };
+    } = {},
   ) {
     await this.ensureLogin();
     // A request without a token is answered with a session logout, so never
     // send one: fetch the page first when we do not have a fresh token yet.
     if (!this.requesttoken) await this.fetchPage();
 
-    const { path, query } = this.ajaxUrl(action, mgrId, options.extra);
+    const { path, query } = this.ajaxUrl(action, mgrId, options.extra, options.page);
     const method = options.method ?? "GET";
 
     const headers: Record<string, string> = {
@@ -348,9 +371,13 @@ export class ZepClient {
     let body: string | undefined;
     if (method === "POST") {
       headers["content-type"] = "application/x-www-form-urlencoded; charset=UTF-8";
-      const form = { ...(options.form ?? {}) };
+      const form: Record<string, string | ReadonlyArray<string>> = { ...(options.form ?? {}) };
       if (this.requesttoken) form.requesttoken = this.requesttoken;
-      body = new URLSearchParams(form).toString();
+      const encoded = new URLSearchParams();
+      for (const [key, value] of Object.entries(form)) {
+        for (const item of Array.isArray(value) ? value : [value]) encoded.append(key, item);
+      }
+      body = encoded.toString();
     }
 
     const res = await this.raw(path, { method, headers, body, query });
@@ -374,14 +401,16 @@ export class ZepClient {
     return { form: parseFormData(html), token: this.requesttoken };
   }
 
-  /** Load the Projektzeiten page and pick up its requesttoken. */
-  private async fetchPage(): Promise<string> {
+  /** Load a ZEP page and pick up its requesttoken. */
+  private async fetchPage(
+    page: { menu: string; action?: string } = { menu: TIME_PAGE.menu, action: "save" },
+  ): Promise<string> {
     if (!this.clientsessid) throw new ZepError("Not logged in.");
     const res = await this.raw("/view/index.php", {
       query: {
         CLIENTSESSID: this.clientsessid,
-        menu: "ProjektzeitVerwaltungMgr",
-        action: "save",
+        menu: page.menu,
+        ...(page.action ? { action: page.action } : {}),
       },
     });
     const html = await res.text();
@@ -396,10 +425,12 @@ export class ZepClient {
    * Like `fetchPage`, but recovers once from a stale session by logging in
    * again. Used by the read paths.
    */
-  private async getPageHtml(): Promise<string> {
+  private async getPageHtml(
+    page: { menu: string; action?: string } = { menu: TIME_PAGE.menu, action: "save" },
+  ): Promise<string> {
     await this.ensureLogin();
     try {
-      return await this.fetchPage();
+      return await this.fetchPage(page);
     } catch {
       this.clientsessid = null;
       this.cookies.clear();
@@ -407,7 +438,7 @@ export class ZepClient {
       if (!result.ok) {
         throw new ZepError(result.message ?? "Login failed", result.attemptsLeft);
       }
-      return this.fetchPage();
+      return this.fetchPage(page);
     }
   }
 
@@ -434,6 +465,85 @@ export class ZepClient {
     return parseWeek(tableHtml, kwDate);
   }
 
+  /**
+   * Read the capacity planning (Einplanung) chart for `from`..`to`.
+   *
+   * The page has no table: the numbers live in the ApexCharts options object
+   * of the chart snippet, which `parsePlan` understands.
+   */
+  async plan(request: ZepPlanRequest): Promise<ZepPlan> {
+    // The Einplanung page carries its own filter form and requesttoken.
+    await this.getPageHtml({ menu: PLAN_PAGE.menu });
+
+    const form: Record<string, string | ReadonlyArray<string>> = {
+      favorit: "NULL",
+      von_bis: "",
+      von_bisquicklinkdata: `${request.from}::${request.to}:`,
+      von: request.from,
+      bis: request.to,
+      projektEinplanung: "1",
+      gestapelt: "1",
+      ff_projektprojektTyp: request.projektTyp ?? "alle",
+      ff_projektstatus: "NULL",
+      ff_projektprojektschlagworteUndOder: "",
+      scale: "0",
+      "Ausführen": "Ausführen",
+    };
+    if (request.projektIds?.length) form["ff_projekt[]"] = request.projektIds;
+
+    const envelope = await this.ajax("filter", PLAN_MGR_ID, {
+      method: "POST",
+      form,
+      page: PLAN_PAGE,
+    });
+
+    const html = envelope.snippets.map((snippet) => snippet.data).join("\n");
+    const plan = parsePlan(html, request.from, request.to);
+    if (!plan) {
+      throw new ZepError(
+        "ZEP returned no readable Einplanung chart. Check the date range (from/to) and that the account has an Einplanung.",
+      );
+    }
+    return plan;
+  }
+
+  /**
+   * Write planned hours/percent into the Einplanung matrix.
+   *
+   * Wire contract taken from the grid's own save handler: the body carries
+   * `edited` as a JSON array of `{p: projektId, d: datum, e: wert, a: 'h'|'%',
+   * b: bemerkung}` entries - `e: null` clears the cell - plus the selection,
+   * the scroll position and the non-working-day switch.
+   */
+  async savePlan(request: ZepPlanSaveRequest): Promise<ZepSaveResult> {
+    // The Einplanung page carries the requesttoken this action needs.
+    await this.getPageHtml({ menu: PLAN_PAGE.menu });
+
+    const edited = request.entries.map((entry) => ({
+      p: entry.projektId,
+      d: entry.date,
+      e: entry.value,
+      // Clearing sends a null unit, exactly like the grid does for a cell it
+      // emptied with the Delete key.
+      a: entry.value === null ? null : entry.unit,
+      b: entry.comment ?? "",
+    }));
+
+    const envelope = await this.ajax("edit", PLAN_SAVE_MGR_ID, {
+      method: "POST",
+      page: PLAN_PAGE,
+      extra: { refresh: "1" },
+      form: {
+        edited: JSON.stringify(edited),
+        selected: JSON.stringify([]),
+        scrollLeft: "0",
+        einplanungAuchAnNichtArbeitstagen: request.auchAnNichtArbeitstagen ? "1" : "0",
+      },
+    });
+
+    return this.verdict(envelope, `${edited.length} Einplanung(en) gespeichert.`);
+  }
+
   /**
    * Turn an ajax envelope into a success/failure verdict.
    *

package/src/clients/zep-parse.ts

@@ -8,7 +8,7 @@
  * tolerant regex parsers rather than a full HTML parser.
  */
 
-import type { ZepBooking, ZepOption, ZepWeek, ZepWeekDay } from "../types.ts";
+import type { ZepBooking, ZepOption, ZepPlan, ZepPlanDay, ZepPlanSlice, ZepWeek, ZepWeekDay } from "../types.ts";
 
 /** Decode the handful of entities ZEP actually uses in labels. */
 export function decodeEntities(input: string): string {
@@ -466,3 +466,286 @@ export function durationBetween(from: string, to: string): string | null {
   const min = diff % 60;
   return `${String(h).padStart(2, "0")}:${String(min).padStart(2, "0")}`;
 }
+
+// --------------------------------------------- capacity planning ("Einplanung")
+
+export interface ZepChartSeries {
+  readonly name: string;
+  readonly type?: string;
+  readonly data: ReadonlyArray<number>;
+}
+
+/** The slice of ZEP's ApexCharts options object that carries the plan data. */
+export interface ZepChartOptions {
+  readonly series: ReadonlyArray<ZepChartSeries>;
+  readonly categories: ReadonlyArray<string>;
+  readonly title: string | null;
+  readonly subtitle: string | null;
+}
+
+interface RawChartOptions {
+  series?: unknown;
+  xaxis?: { categories?: unknown };
+  title?: { text?: unknown };
+  subtitle?: { text?: unknown };
+}
+
+/** Trailing `[16,00 h]` ZEP appends to every series name. */
+const SERIES_HOURS_RE = /\s*\[([\d.,]+)\s*h\]\s*$/;
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+/**
+ * Slice a balanced `{...}` or `[...]` block starting at `start`.
+ *
+ * String-aware on purpose: series names are project labels like
+ * `K-10000-00001 (Contoso) [16,00 h]`, so brackets inside string literals
+ * must not be counted as nesting.
+ */
+function sliceBalanced(text: string, start: number): string | null {
+  const open = text[start];
+  if (open !== "{" && open !== "[") return null;
+  const close = open === "{" ? "}" : "]";
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < text.length; i += 1) {
+    const char = text[i]!;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === open) depth += 1;
+    else if (char === close) {
+      depth -= 1;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Turn ZEP's options object into parseable JSON.
+ *
+ * It is JavaScript, not JSON: the axis label and tooltip formatters are real
+ * function expressions (`"formatter":function(val, index) { ... }`). Their
+ * values carry no plan data, so each one is replaced by `null`.
+ */
+function stripJsFunctions(text: string): string {
+  let result = "";
+  let index = 0;
+
+  while (index < text.length) {
+    const found = text.indexOf("function", index);
+    if (found === -1) {
+      result += text.slice(index);
+      break;
+    }
+
+    // Only treat it as code in value position; a project label could contain
+    // the word "function" as text.
+    const before = text.slice(0, found).replace(/\s+$/, "").slice(-1);
+    if (before !== ":" && before !== "," && before !== "[" && before !== "(") {
+      result += text.slice(index, found + "function".length);
+      index = found + "function".length;
+      continue;
+    }
+
+    const bodyStart = text.indexOf("{", found + "function".length);
+    const body = bodyStart === -1 ? null : sliceBalanced(text, bodyStart);
+    // keep everything before the keyword - it is part of the object
+    result += text.slice(index, found) + "null";
+    if (!body) break;
+    index = bodyStart + body.length;
+  }
+  return result;
+}
+
+/**
+ * Replace bare JavaScript identifiers that are not JSON keywords with `null`.
+ *
+ * ZEP's object is JavaScript, not JSON: axis locales arrive as a reference to
+ * the page's global (`"locales":[apex_lang_de]`), which JSON.parse rejects.
+ */
+function neutraliseJsValues(jsonish: string): string {
+  let result = "";
+  let inString = false;
+  let escaped = false;
+  let index = 0;
+
+  while (index < jsonish.length) {
+    const char = jsonish[index]!;
+    if (inString) {
+      result += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      index += 1;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      result += char;
+      index += 1;
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(char)) {
+      let end = index;
+      while (end < jsonish.length && /[A-Za-z0-9_$.]/.test(jsonish[end]!)) end += 1;
+      const token = jsonish.slice(index, end);
+      result += token === "true" || token === "false" || token === "null" ? token : "null";
+      index = end;
+      continue;
+    }
+    result += char;
+    index += 1;
+  }
+  return result;
+}
+
+/** Read the ApexCharts options object ZEP embeds next to a chart container. */
+export function extractChartOptions(html: string): ZepChartOptions | null {
+  const marker = /var\s+options\w*\s*=\s*/.exec(html);
+  if (!marker) return null;
+
+  const start = html.indexOf("{", marker.index + marker[0].length);
+  if (start === -1) return null;
+
+  const raw = sliceBalanced(html, start);
+  if (!raw) return null;
+
+  let parsed: RawChartOptions;
+  try {
+    parsed = JSON.parse(neutraliseJsValues(stripJsFunctions(raw))) as RawChartOptions;
+  } catch {
+    return null;
+  }
+
+  const rawSeries = Array.isArray(parsed.series) ? parsed.series : [];
+  const series: ZepChartSeries[] = [];
+  for (const entry of rawSeries) {
+    if (!entry || typeof entry !== "object") continue;
+    const shaped = entry as { name?: unknown; type?: unknown; data?: unknown };
+    if (typeof shaped.name !== "string" || shaped.name === "") continue;
+    series.push({
+      name: shaped.name,
+      type: typeof shaped.type === "string" ? shaped.type : undefined,
+      data: Array.isArray(shaped.data)
+        ? shaped.data.filter((value): value is number => typeof value === "number")
+        : [],
+    });
+  }
+
+  const categories = Array.isArray(parsed.xaxis?.categories)
+    ? parsed.xaxis.categories.filter((value): value is string => typeof value === "string")
+    : [];
+
+  return {
+    series,
+    categories,
+    title: typeof parsed.title?.text === "string" ? parsed.title.text : null,
+    subtitle: typeof parsed.subtitle?.text === "string" ? parsed.subtitle.text : null,
+  };
+}
+
+/** `[16,00 h]` -> 16, `[108,80 h]` -> 108.8 */
+function hoursFromSeriesName(name: string): number | null {
+  const match = SERIES_HOURS_RE.exec(name);
+  if (!match) return null;
+  const value = Number((match[1] ?? "").replace(/\./g, "").replace(",", "."));
+  return Number.isFinite(value) ? value : null;
+}
+
+function addDays(iso: string, days: number): string {
+  const date = new Date(`${iso}T00:00:00Z`);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Parse the Einplanung chart into days, capacity and planned hours.
+ *
+ * ZEP renders three kinds of series: `Verfügbarkeit [108,80 h]` (the person's
+ * capacity per day), one `bar` series per project and `gesamt [82,40 h]` (the
+ * daily total). The kind is detected on the name prefix and only falls back to
+ * the chart type.
+ */
+export function parsePlan(html: string, from: string, to: string): ZepPlan | null {
+  const options = extractChartOptions(html);
+  if (!options || options.series.length === 0) return null;
+
+  let availability: ReadonlyArray<number> = [];
+  let totals: ReadonlyArray<number> = [];
+  const projectSeries: Array<{ name: string; data: ReadonlyArray<number>; stated: number | null }> = [];
+
+  for (const series of options.series) {
+    const label = series.name.replace(SERIES_HOURS_RE, "").trim();
+    if (/^verf/i.test(label) || series.type === "area") {
+      availability = series.data;
+    } else if (/^gesamt/i.test(label) || series.type === "line") {
+      totals = series.data;
+    } else {
+      projectSeries.push({ name: label, data: series.data, stated: hoursFromSeriesName(series.name) });
+    }
+  }
+
+  const columnCount = Math.max(
+    options.categories.length,
+    ...options.series.map((series) => series.data.length),
+    0,
+  );
+  if (columnCount === 0) return null;
+
+  const days: ZepPlanDay[] = [];
+  const summed = new Map<string, number>();
+
+  for (let index = 0; index < columnCount; index += 1) {
+    const slices: ZepPlanSlice[] = [];
+    for (const series of projectSeries) {
+      const hours = series.data[index] ?? 0;
+      if (hours <= 0) continue;
+      slices.push({ project: series.name, hours: round2(hours) });
+      summed.set(series.name, round2((summed.get(series.name) ?? 0) + hours));
+    }
+    slices.sort((a, b) => b.hours - a.hours);
+
+    const available = availability[index];
+    const total = totals[index] ?? slices.reduce((sum, slice) => sum + slice.hours, 0);
+
+    days.push({
+      label: options.categories[index] ?? "",
+      date: addDays(from, index),
+      available: available === undefined ? null : round2(available),
+      planned: round2(total ?? 0),
+      slices,
+    });
+  }
+
+  return {
+    title: options.title,
+    from,
+    to,
+    range: options.subtitle,
+    capacity: round2(days.reduce((sum, day) => sum + (day.available ?? 0), 0)),
+    planned: round2(days.reduce((sum, day) => sum + day.planned, 0)),
+    // ZEP states each project's range total in its series name ([16,00 h]);
+    // prefer that number, fall back to our own sum of the days.
+    projects: projectSeries
+      .map((series) => ({
+        project: series.name,
+        hours: series.stated ?? summed.get(series.name) ?? 0,
+      }))
+      .sort((a, b) => b.hours - a.hours),
+    days,
+  };
+}

package/src/formatting/formatters.ts

@@ -2,7 +2,7 @@
  * Pure functions that turn ZEP domain data into text for the model/user.
  */
 
-import type { ZepFormData, ZepSaveResult, ZepWeek } from "../types.ts";
+import type { ZepFormData, ZepPlan, ZepPlanEntry, ZepSaveResult, ZepWeek } from "../types.ts";
 
 function pad(value: string, width: number): string {
   return value.length >= width ? value : value + " ".repeat(width - value.length);
@@ -91,3 +91,73 @@ export function formatMoneyTable(headers: ReadonlyArray<string>, rows: ReadonlyA
     cells.map((c, i) => pad(c ?? "", widths[i] ?? 0)).join("  ").trimEnd();
   return [line(headers), widths.map((w) => "-".repeat(w)).join("  "), ...rows.map(line)].join("\n");
 }
+
+// ------------------------------------------------- capacity planning (Einplanung)
+
+/** `16` -> `16,00` (ZEP prints hours with a comma). */
+function formatHours(value: number): string {
+  return value.toFixed(2).replace(".", ",");
+}
+
+const WEEKDAYS = ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"] as const;
+
+function dayParts(iso: string): { weekday: string; short: string } {
+  const date = new Date(`${iso}T00:00:00Z`);
+  const weekday = WEEKDAYS[date.getUTCDay()] ?? "??";
+  const short = `${String(date.getUTCDate()).padStart(2, "0")}.${String(date.getUTCMonth() + 1).padStart(2, "0")}.`;
+  return { weekday, short };
+}
+
+export function formatPlan(plan: ZepPlan): string {
+  const lines: string[] = [];
+  lines.push(`Einplanung${plan.title ? ` ${plan.title}` : ""}  (${plan.range ?? `${plan.from} - ${plan.to}`})`);
+
+  const utilization = plan.capacity > 0 ? Math.round((plan.planned / plan.capacity) * 100) : null;
+  const overBooked = plan.days.filter(
+    (day) => day.available !== null && day.planned > day.available + 0.001,
+  ).length;
+
+  lines.push(
+    `Kapazität ${formatHours(plan.capacity)} h | geplant ${formatHours(plan.planned)} h` +
+      `${utilization === null ? "" : ` | Auslastung ${utilization} %`}` +
+      `${overBooked > 0 ? ` | ${overBooked} Tag(e) überbucht` : ""}`,
+  );
+  lines.push("");
+
+  const plannedDays = plan.days.filter((day) => day.planned > 0);
+  if (plannedDays.length === 0) {
+    lines.push("(keine Einplanung im Zeitraum)");
+  }
+  for (const day of plannedDays) {
+    const { weekday, short } = dayParts(day.date);
+    const slices = day.slices
+      .map((slice) => `${slice.project} ${formatHours(slice.hours)}`)
+      .join(" | ");
+    lines.push(
+      `${weekday} ${short}  ${formatHours(day.planned)}` +
+        `${day.available === null ? "" : ` / ${formatHours(day.available)}`} h  ${slices}`,
+    );
+  }
+
+  if (plan.projects.length > 0) {
+    lines.push("", "Planstunden je Projekt:");
+    for (const project of plan.projects) {
+      lines.push(`    ${formatHours(project.hours).padStart(6)} h  ${project.project}`);
+    }
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+/** One line per changed cell, used by zep_plan_set. */
+export function formatPlanEntries(entries: ReadonlyArray<ZepPlanEntry>): string {
+  return entries
+    .map((entry) => {
+      const value =
+        entry.value === null ? "geleert" : `${formatHours(entry.value)} ${entry.unit === "%" ? "%" : "h"}`;
+      return `    ${entry.date}  Projekt ${entry.projektId}  ${value}${
+        entry.comment ? `  "${entry.comment}"` : ""
+      }`;
+    })
+    .join("\n");
+}

package/src/tools/shared.ts

@@ -42,3 +42,26 @@ export function toHhMm(value: string): string {
   if (hourOnly) return `${hourOnly[1]!.padStart(2, "0")}:00`;
   throw new Error(`Unparseable time: "${value}" (use HH:MM)`);
 }
+
+/**
+ * Match an id exactly first, then an exact label, then a label substring.
+ * Used by every tool that accepts "id or part of the label".
+ */
+export function matchOption<T extends { id: string; label: string }>(
+  options: ReadonlyArray<T>,
+  reference: string,
+): T | undefined {
+  const needle = reference.trim().toLowerCase();
+  return (
+    options.find((option) => option.id === reference.trim()) ??
+    options.find((option) => option.label.toLowerCase() === needle) ??
+    options.find((option) => option.label.toLowerCase().includes(needle))
+  );
+}
+
+/** Shift an ISO date by whole days. */
+export function addDays(iso: string, days: number): string {
+  const date = new Date(`${iso}T00:00:00Z`);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}

package/src/tools/zep-book.ts

@@ -12,7 +12,7 @@ import { durationBetween } from "../clients/zep-parse.ts";
 import { ZepError } from "../clients/zep-client.ts";
 import { updateProfile } from "../config.ts";
 import type { ZepBookingRequest, ZepFormData, ZepOption } from "../types.ts";
-import { errorResult, textResult, toHhMm, toIsoDate, type ToolResult } from "./shared.ts";
+import { errorResult, matchOption, textResult, toHhMm, toIsoDate, type ToolResult } from "./shared.ts";
 
 interface EntryParam {
   von: string;
@@ -309,19 +309,6 @@ export const ZepBookTool = {
   },
 };
 
-/** Match an id exactly first, then an exact label, then a label substring. */
-function matchOption(
-  options: ReadonlyArray<{ id: string; label: string }>,
-  reference: string,
-): { id: string; label: string } | undefined {
-  const needle = reference.trim().toLowerCase();
-  return (
-    options.find((o) => o.id === reference.trim()) ??
-    options.find((o) => o.label.toLowerCase() === needle) ??
-    options.find((o) => o.label.toLowerCase().includes(needle))
-  );
-}
-
 function resolveTaetigkeit(scope: ProjectScope, reference: string | undefined): string {
   if (reference) {
     const match = matchOption(scope.taetigkeiten, reference);

package/src/tools/zep-plan-set.ts

@@ -0,0 +1,141 @@
+/**
+ * zep_plan_set -- write planned hours into the ZEP capacity planning.
+ *
+ * ZEP's Einplanung matrix stores one value per project and day, either as
+ * hours ("h") or as a percentage of that day's availability ("%"). The grid
+ * posts only the cells it marked as edited, so a save merges into the existing
+ * plan; `value: null` clears a cell.
+ */
+
+import { Type } from "typebox";
+
+import { createClient } from "../session.ts";
+import { formatPlan, formatPlanEntries } from "../formatting/formatters.ts";
+import { errorResult, matchOption, textResult, toIsoDate, type ToolResult } from "./shared.ts";
+import type { ZepPlanEntry } from "../types.ts";
+
+interface CellParams {
+  datum?: string;
+  projekt?: string;
+  stunden?: number;
+  prozent?: number;
+  leeren?: boolean;
+  bemerkung?: string;
+}
+
+const CellSchema = Type.Object({
+  datum: Type.Optional(Type.String({ description: "Day (YYYY-MM-DD or DD.MM.YYYY). Defaults to today." })),
+  projekt: Type.Optional(
+    Type.String({ description: "Project id (e.g. '371') or part of its label." }),
+  ),
+  stunden: Type.Optional(Type.Number({ description: "Planned hours for that day." })),
+  prozent: Type.Optional(
+    Type.Number({ description: "Planned percentage of the day's availability (ZEP stores '%')." }),
+  ),
+  leeren: Type.Optional(Type.Boolean({ description: "Clear the cell instead of setting a value." })),
+  bemerkung: Type.Optional(Type.String({ description: "Note stored with the plan cell." })),
+});
+
+export const ZepPlanSetTool = {
+  name: "zep_plan_set",
+  label: "ZEP Einplanung setzen",
+  description:
+    "Write into the ZEP capacity planning (Einplanung / Kapa-Planung): set planned hours or a percentage for one project and day, or clear the cell. Give one cell with the top-level fields or several with 'entries'. Use dryRun to see the exact request without saving. Every save is verified by re-reading the plan.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    datum: Type.Optional(Type.String({ description: "Day for a single cell. Defaults to today." })),
+    projekt: Type.Optional(Type.String({ description: "Project id or part of its label." })),
+    stunden: Type.Optional(Type.Number({ description: "Planned hours." })),
+    prozent: Type.Optional(Type.Number({ description: "Planned percentage of the day's availability." })),
+    leeren: Type.Optional(Type.Boolean({ description: "Clear the cell instead of setting a value." })),
+    bemerkung: Type.Optional(Type.String({ description: "Note stored with the plan cell." })),
+    entries: Type.Optional(
+      Type.Array(CellSchema, { description: "Several cells in one call." }),
+    ),
+    dryRun: Type.Optional(
+      Type.Boolean({ description: "Resolve everything and show what would be sent, without saving." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: CellParams & { profile?: string; entries?: ReadonlyArray<CellParams>; dryRun?: boolean },
+  ): Promise<ToolResult> {
+    try {
+      const cells: CellParams[] = params.entries?.length ? [...params.entries] : [params];
+      if (cells.length === 0) return errorResult("No plan cell given.");
+
+      const { client, profileName } = await createClient(params.profile);
+      const { form } = await client.loadForm();
+
+      const entries: ZepPlanEntry[] = [];
+      for (const cell of cells) {
+        const date = toIsoDate(cell.datum ?? params.datum);
+        const reference = cell.projekt ?? params.projekt;
+        if (!reference) return errorResult("No project given: pass 'projekt' (id or label).");
+
+        const project = matchOption(form.projects, reference);
+        if (!project) {
+          return errorResult(
+            `No project matches "${reference}". Known projects: ${form.projects
+              .map((option) => `${option.id}=${option.label}`)
+              .join(" | ")}`,
+          );
+        }
+
+        const hours = cell.stunden;
+        const percent = cell.prozent;
+        const clear = cell.leeren ?? false;
+        const given = [hours !== undefined, percent !== undefined, clear].filter(Boolean).length;
+        if (given !== 1) {
+          return errorResult(
+            `Give exactly one of 'stunden', 'prozent' or 'leeren' for ${date} / ${project.label}.`,
+          );
+        }
+
+        const comment = cell.bemerkung ?? params.bemerkung;
+        entries.push({
+          projektId: project.id,
+          date,
+          value: clear ? null : (hours ?? percent ?? null),
+          unit: percent !== undefined ? "%" : "h",
+          ...(comment ? { comment } : {}),
+        });
+      }
+
+      const preview =
+        `${params.dryRun ? "DRY RUN - nothing saved.\n\n" : ""}` +
+        `Einplanung (${entries.length} Zelle(n)):\n${formatPlanEntries(entries)}`;
+
+      if (params.dryRun) return textResult(preview, { profile: profileName, dryRun: true });
+
+      const saved = await client.savePlan({ entries });
+      if (!saved.ok) {
+        return errorResult(`ZEP rejected the Einplanung: ${saved.error ?? "unspecified error"}`);
+      }
+
+      // Read back what ZEP stored for the touched days.
+      const dates = entries.map((entry) => entry.date).sort();
+      const from = dates[0]!;
+      const to = dates[dates.length - 1]!;
+      const plan = await client.plan({ from, to });
+
+      return textResult(
+        `${preview}\n\n${saved.message ?? "saved"}\n\nKontrolle (${from} - ${to}):\n${formatPlan(plan)}`,
+        {
+          profile: profileName,
+          saved: true,
+          entries: entries.length,
+          from,
+          to,
+          planned: plan.planned,
+          capacity: plan.capacity,
+        },
+      );
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};

package/src/tools/zep-plan.ts

@@ -0,0 +1,77 @@
+/**
+ * zep_plan -- read the ZEP capacity planning ("Einplanung", Kapa-Planung).
+ */
+
+import { Type } from "typebox";
+
+import { createClient } from "../session.ts";
+import { formatPlan } from "../formatting/formatters.ts";
+import { addDays, errorResult, textResult, toIsoDate, type ToolResult } from "./shared.ts";
+
+export const ZepPlanTool = {
+  name: "zep_plan",
+  label: "ZEP Einplanung",
+  description:
+    "Show the ZEP capacity planning (Einplanung / Kapa-Planung): per day the planned hours, the available hours and the per-project breakdown, plus total capacity, planned hours and utilization. Read-only. Defaults to today plus 30 days.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    von: Type.Optional(
+      Type.String({
+        description: "Start date (YYYY-MM-DD or DD.MM.YYYY). Defaults to today.",
+      }),
+    ),
+    bis: Type.Optional(
+      Type.String({
+        description: "End date. Defaults to 30 days after 'von' (ZEP's own default range).",
+      }),
+    ),
+    projektTyp: Type.Optional(
+      Type.String({
+        description: "ZEP Projekttyp filter: 'alle' (default), 'intern' or 'kunden'.",
+      }),
+    ),
+    projekte: Type.Optional(
+      Type.Array(Type.String(), {
+        description: "Restrict the plan to these project ids.",
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      profile?: string;
+      von?: string;
+      bis?: string;
+      projektTyp?: string;
+      projekte?: ReadonlyArray<string>;
+    },
+  ): Promise<ToolResult> {
+    try {
+      const from = toIsoDate(params.von);
+      const to = params.bis ? toIsoDate(params.bis) : addDays(from, 30);
+
+      const { client, profileName } = await createClient(params.profile);
+      const plan = await client.plan({
+        from,
+        to,
+        projektTyp: params.projektTyp,
+        projektIds: params.projekte,
+      });
+
+      return textResult(formatPlan(plan), {
+        profile: profileName,
+        from: plan.from,
+        to: plan.to,
+        capacity: plan.capacity,
+        planned: plan.planned,
+        projects: plan.projects.length,
+        days: plan.days.length,
+      });
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};

package/src/types.ts

@@ -156,3 +156,77 @@ export interface SetupParams {
   mandant?: string;
   baseUrl?: string;
 }
+
+// ------------------------------------------------- capacity planning (Einplanung)
+
+/** One project's planned hours on one day. */
+export interface ZepPlanSlice {
+  readonly project: string;
+  readonly hours: number;
+}
+
+/** One day on the Einplanung chart. */
+export interface ZepPlanDay {
+  /** Day label exactly as ZEP prints it: `Heute`, `Morgen` or `19.09.`. */
+  readonly label: string;
+  /** Resolved ISO date of that column. */
+  readonly date: string;
+  /** Available hours from ZEP's `Verfügbarkeit` series, null when absent. */
+  readonly available: number | null;
+  /** Planned hours from ZEP's `gesamt` series. */
+  readonly planned: number;
+  /** Planned hours per project on this day, largest first. */
+  readonly slices: ReadonlyArray<ZepPlanSlice>;
+}
+
+/** A project's planned hours over the whole requested range. */
+export interface ZepPlanProject {
+  readonly project: string;
+  readonly hours: number;
+}
+
+/** Result of reading the Einplanung (capacity planning) chart. */
+export interface ZepPlan {
+  /** Chart title - the employee the plan belongs to. */
+  readonly title: string | null;
+  /** Requested range, ISO dates. */
+  readonly from: string;
+  readonly to: string;
+  /** Range as ZEP prints it in the chart subtitle. */
+  readonly range: string | null;
+  /** Sum of the availability series. */
+  readonly capacity: number;
+  /** Sum of the `gesamt` series. */
+  readonly planned: number;
+  readonly projects: ReadonlyArray<ZepPlanProject>;
+  readonly days: ReadonlyArray<ZepPlanDay>;
+}
+
+export interface ZepPlanRequest {
+  readonly from: string;
+  readonly to: string;
+  /** `alle`, `intern` or `kunden` - ZEP's Projekttyp filter. */
+  readonly projektTyp?: string;
+  /** Project ids for ZEP's Projekt filter. */
+  readonly projektIds?: ReadonlyArray<string>;
+}
+
+/**
+ * One cell of the Einplanung matrix as ZEP stores it.
+ *
+ * ZEP keeps the plan per project and day, either as hours (`h`) or as a
+ * percentage of that day's availability (`%`). `value: null` clears the cell.
+ */
+export interface ZepPlanEntry {
+  readonly projektId: string;
+  readonly date: string;
+  readonly value: number | null;
+  readonly unit: "h" | "%";
+  readonly comment?: string;
+}
+
+export interface ZepPlanSaveRequest {
+  readonly entries: ReadonlyArray<ZepPlanEntry>;
+  /** ZEP's "Einplanung auch an Nicht-Arbeitstagen" switch. */
+  readonly auchAnNichtArbeitstagen?: boolean;
+}