studiograph 1.3.48-next.2 → 1.3.48-next.201

package/dist/services/csv-service.js

@@ -1,66 +1,65 @@
 /**
  * CSV Service
  *
- * Parses, stringifies, validates, and filters CSV data for dataset entities.
- * Uses csv-parse and csv-stringify for reliable CSV handling.
+ * Parses, stringifies, and filters CSV data for dataset entities.
+ * Conventional CSV: the header row is the column list, every cell is a
+ * string. There is no typed column schema — callers derive columns from the
+ * header. Uses csv-parse and csv-stringify for reliable CSV handling.
  */
 import { parse } from 'csv-parse/sync';
 import { stringify } from 'csv-stringify/sync';
 export class CSVService {
     /**
-     * Parse CSV text into typed rows using the declared schema.
-     * Returns an empty array for CSV with headers only (no data rows).
+     * Parse CSV text into string-keyed rows. The header row supplies the
+     * column names. Returns an empty array for empty CSV or header-only CSV.
      */
-    parseRows(csvText, schema) {
+    parseRows(csvText) {
         const trimmed = csvText.trim();
         if (!trimmed) {
             return [];
         }
-        const records = parse(trimmed, {
+        return parse(trimmed, {
             columns: true,
             skip_empty_lines: true,
             trim: true,
         });
-        return records.map(record => this.validateRow(record, schema));
     }
     /**
-     * Stringify rows back to CSV text (header row + data rows).
+     * Column names from the CSV header row. Empty array for empty CSV.
      */
-    stringifyRows(rows, schema) {
-        const columns = schema.map(col => col.name);
-        if (rows.length === 0) {
-            return columns.join(',') + '\n';
+    columns(csvText) {
+        const trimmed = csvText.trim();
+        if (!trimmed) {
+            return [];
         }
-        return stringify(rows, {
-            header: true,
-            columns,
-            cast: {
-                boolean: (value) => String(value),
-            },
+        const header = parse(trimmed, {
+            columns: false,
+            skip_empty_lines: true,
+            trim: true,
+            to: 1,
         });
+        return header.length > 0 ? header[0] : [];
     }
     /**
-     * Validate and coerce a raw string record against the schema.
-     * Throws on missing required fields or type coercion failure.
+     * Stringify rows back to CSV text. `columns` fixes the column order and set;
+     * cells missing from a row serialize empty, keys not in `columns` are
+     * dropped. With `includeHeader: false` only the data rows are emitted (used
+     * to append rows after an existing body without rewriting it).
      */
-    validateRow(row, schema) {
-        const result = {};
-        for (const col of schema) {
-            const raw = row[col.name];
-            if (raw === undefined || raw === null || raw === '') {
-                if (col.required) {
-                    throw new Error(`Missing required field: ${col.name}`);
-                }
-                result[col.name] = null;
-                continue;
-            }
-            result[col.name] = this.coerceValue(raw, col);
+    stringifyRows(rows, columns, includeHeader = true) {
+        if (columns.length === 0) {
+            return '';
         }
-        return result;
+        if (rows.length === 0) {
+            return includeHeader ? columns.join(',') + '\n' : '';
+        }
+        return stringify(rows, { header: includeHeader, columns });
     }
     /**
-     * Filter rows using a DatasetFilter.
-     * Supports equality, { gte, lte } for numbers/dates, { contains } for strings.
+     * Filter rows. Supports equality (`{ col: 'x' }`), substring
+     * (`{ col: { contains } }`), and range (`{ col: { gte, lte } }`). Range
+     * comparisons are numeric when both the cell and the bound parse as finite
+     * numbers, otherwise lexical — sensible defaults for an untyped CSV.
      */
     filterRows(rows, filter) {
         return rows.filter(row => {
@@ -73,71 +72,35 @@ export class CSVService {
                             return false;
                         }
                     }
-                    if (gte !== undefined) {
-                        if (value === null || value === undefined)
-                            return false;
-                        if (typeof value === 'string' && typeof gte === 'string') {
-                            if (value < gte)
-                                return false;
-                        }
-                        else {
-                            if (value < gte)
-                                return false;
-                        }
-                    }
-                    if (lte !== undefined) {
-                        if (value === null || value === undefined)
-                            return false;
-                        if (typeof value === 'string' && typeof lte === 'string') {
-                            if (value > lte)
-                                return false;
-                        }
-                        else {
-                            if (value > lte)
-                                return false;
-                        }
+                    if (gte !== undefined && compareCell(value, gte) < 0) {
+                        return false;
                     }
-                }
-                else {
-                    // Equality check
-                    if (value !== condition) {
+                    if (lte !== undefined && compareCell(value, lte) > 0) {
                         return false;
                     }
                 }
+                else if (value !== condition) {
+                    return false;
+                }
             }
             return true;
         });
     }
-    coerceValue(raw, col) {
-        switch (col.type) {
-            case 'number': {
-                const n = Number(raw);
-                if (isNaN(n)) {
-                    throw new Error(`Invalid number value for column "${col.name}": ${raw}`);
-                }
-                return n;
-            }
-            case 'boolean': {
-                const lower = raw.toLowerCase();
-                if (lower === 'true' || lower === '1' || lower === 'yes')
-                    return true;
-                if (lower === 'false' || lower === '0' || lower === 'no')
-                    return false;
-                throw new Error(`Invalid boolean value for column "${col.name}": ${raw}`);
-            }
-            case 'date': {
-                // Store dates as ISO string; validate that the value is parseable
-                const d = new Date(raw);
-                if (isNaN(d.getTime())) {
-                    throw new Error(`Invalid date value for column "${col.name}": ${raw}`);
-                }
-                // Return the original date string (YYYY-MM-DD) rather than converting to full ISO
-                return raw;
-            }
-            case 'string':
-            default:
-                return raw;
-        }
+}
+/**
+ * Compare a CSV cell against a bound. Numeric when both sides parse as finite
+ * numbers, otherwise string comparison. Returns <0, 0, or >0; an
+ * absent/undefined cell sorts before any bound.
+ */
+function compareCell(value, bound) {
+    if (value === undefined || value === null)
+        return -1;
+    const vNum = Number(value);
+    const bNum = Number(bound);
+    if (value !== '' && !Number.isNaN(vNum) && !Number.isNaN(bNum)) {
+        return vNum < bNum ? -1 : vNum > bNum ? 1 : 0;
     }
+    const b = String(bound);
+    return value < b ? -1 : value > b ? 1 : 0;
 }
 //# sourceMappingURL=csv-service.js.map

package/dist/services/csv-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"csv-service.js","sourceRoot":"","sources":["../../src/services/csv-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"csv-service.js","sourceRoot":"","sources":["../../src/services/csv-service.ts"],"names":[],"mappings":"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"}

package/dist/services/entity-mutations.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Shared payload preparation for `create_entity` / `update_entity` across
+ * the MCP surface ([src/mcp/tools.ts](../mcp/tools.ts)) and the agent surface
+ * ([src/agent/tools/graph-tools.ts](../agent/tools/graph-tools.ts)).
+ *
+ * Owns:
+ *   - Actor identity build (`buildActor`).
+ *   - Base-field auto-stamping for create (`stampCreateBaseFields`).
+ *   - Person.status synonym normalization (`normalizePersonStatus`).
+ *   - Two composers (`prepareCreatePayload`, `prepareUpdatePayload`) that
+ *     return ready-to-pass options for `graph.create` / `graph.update`.
+ *
+ * Does NOT own surface-specific concerns: MCP keeps its allowlist check,
+ * `withAgentActivity` chip wiring, `emitEntityChange` broadcast, and rich
+ * diagnostics; the agent keeps its content sanitiser, workspace dedup
+ * warning, eager-skill permission gate, user_handle bridge checks, and
+ * `onMutation` / `onAgentActivity` callbacks.
+ *
+ * Errors from `graph.update` — including `LiveEditorPendingError` from the
+ * Phase 2 server-write live-typing guard — propagate through the composers
+ * unchanged; callers map them to their surface's error format.
+ */
+import type { AuthUser } from './auth-service.js';
+import type { GitUser } from './git.js';
+import type { CreateEntityOptions, UpdateEntityOptions, EntityFile } from '../core/graph.js';
+import type { EntityType } from '../core/validation.js';
+import type { BodyWriteResult } from '../server/body-write-coordinator.js';
+/**
+ * Person.status accepts only `current` | `former` per PersonSchema, but
+ * real-world payloads from external agents carry many synonyms. Map them
+ * to canonical before validation rejects the call. Unknown values fall
+ * through unchanged so validation surfaces them loudly.
+ *
+ * On create: defaults missing status to `current`.
+ * On update: only normalises when status is supplied — don't fabricate a
+ * field the caller didn't ask to change.
+ */
+export declare const PERSON_STATUS_ALIASES: Record<string, 'current' | 'former'>;
+/**
+ * Build the git-author / audit-trail identity for an authenticated session.
+ * `handle` is the canonical id stamped into `created_by` / `updated_by` and
+ * used as the git author; falls back to `user-<id>` if a token from before
+ * the handle backfill is still in use.
+ *
+ * Surfaces that may run without an authenticated user (CLI, server-only
+ * automations, tests) should keep their existing orchestrator `GitUser` and
+ * pass it directly to the composers — `buildActor` requires an `AuthUser`.
+ */
+export declare function buildActor(user: AuthUser): GitUser;
+/**
+ * EntityBaseSchema requires entity_id, created_at, updated_at, created_by,
+ * and updated_by. External callers (Claude Desktop, Cursor, the agent)
+ * typically pass only type-specific data plus the top-level entity_id, so
+ * the helper seeds the rest rather than forcing every caller to know the
+ * convention. Caller-supplied values for created_at / created_by / etc.
+ * win; entity_id is always overwritten to match the top-level arg (it is
+ * the lookup key and cannot diverge from the filename).
+ */
+export declare function stampCreateBaseFields(data: Record<string, unknown>, entityId: string, actorHandle: string): Record<string, unknown>;
+export declare function normalizePersonStatus(data: Record<string, unknown>, isCreate: boolean): Record<string, unknown>;
+/** Minimal workspace surface the ref validator needs: resolve an entity id to
+ *  its type, workspace-wide. `WorkspaceManager.findEntityById` satisfies this. */
+export interface RefResolver {
+    findEntityById(entityId: string): {
+        entityType: string;
+    } | null;
+}
+/** Optional surface to validate an account/user reference (`[[user:<id>]]`).
+ *  When supplied, a ref to a non-existent account is rejected; when omitted,
+ *  well-formed user refs pass (mirrors the forward-ref tolerance for entities).
+ *  `AuthService.getUserById` satisfies this. */
+export interface UserRefResolver {
+    userExists(userId: string): boolean;
+}
+/** Thrown when a reference field resolves to the wrong entity type (e.g. a
+ *  task `assignee` pointing at a deal/org), or a user ref is used where the
+ *  field expects a non-person entity. Callers map it to their surface's
+ *  error envelope (HTTP 400, MCP fail, agent `{ success: false }`). */
+export declare class EntityRefError extends Error {
+    readonly field: string;
+    readonly expectedType: string;
+    readonly actualType: string;
+    readonly target: string;
+    readonly code = "ASSIGNEE_NOT_PERSON";
+    constructor(field: string, expectedType: string, actualType: string, target: string);
+}
+/** Thrown when an account reference (`[[user:<id>]]`) names an account that
+ *  doesn't exist in this workspace. Only raised when a {@link UserRefResolver}
+ *  is supplied to {@link assertEntityRefs}. */
+export declare class UnknownUserRefError extends Error {
+    readonly field: string;
+    readonly userId: string;
+    readonly code = "UNKNOWN_USER_REF";
+    constructor(field: string, userId: string);
+}
+/**
+ * Enforce `refType` field scoping for an entity create/update payload. For
+ * each built-in ref field present on `data`, parse the reference and:
+ *   - ENTITY ref: resolve it and throw {@link EntityRefError} when it resolves
+ *     to a different entity type. Unresolved (forward-ref) and empty pass.
+ *   - USER ref (`[[user:<id>]]`): accepted only where the field expects a
+ *     `person` (a user IS a person-identity). With a {@link UserRefResolver}
+ *     supplied, a ref to a non-existent account throws {@link UnknownUserRefError}.
+ * No-op for types without ref fields (everything except `task` today).
+ *
+ * `data` may be a partial update payload — only fields actually present are
+ * checked, so a content-only or unrelated-field update never trips this.
+ */
+export declare function assertEntityRefs(resolver: RefResolver, entityType: string, data: Record<string, unknown> | undefined, userResolver?: UserRefResolver): void;
+export interface PrepareCreateInput {
+    entityType: EntityType;
+    entityId: string;
+    data: Record<string, unknown>;
+    content?: string;
+    folderPath?: string;
+    commitMessage?: string;
+}
+/**
+ * Compose the options for `graph.create`. Stamps base fields, mirrors
+ * `entity_id` from the top-level arg into frontmatter, normalises
+ * `person.status` synonyms, and threads the actor through as the git
+ * commit author. The caller still owns access checks, allowlist
+ * enforcement, content sanitisation, and broadcast/chip wiring.
+ */
+export declare function prepareCreatePayload(input: PrepareCreateInput, actor: GitUser): CreateEntityOptions;
+export interface PrepareUpdateInput {
+    entityType: EntityType;
+    entityId: string;
+    data?: Record<string, unknown>;
+    content?: string;
+    commitMessage?: string;
+}
+/**
+ * Compose the options for `graph.update`. Mirrors `entity_id` from the
+ * top-level arg into frontmatter (defensive against callers that pass a
+ * disagreeing value), normalises `person.status` synonyms when status is
+ * supplied, and declares `source: 'server-write'` whenever content is
+ * present so the body-write path engages the per-doc lock + live-editor
+ * guard. `graph.update` re-stamps `updated_at` / `updated_by` itself.
+ */
+export declare function prepareUpdatePayload(input: PrepareUpdateInput, actor: GitUser): UpdateEntityOptions;
+/**
+ * Thrown when an update wrote but produced no on-disk diff despite the
+ * caller intending a change — i.e. the validator dropped unknown fields or
+ * the supplied content matched the existing body. Carries the entity coords
+ * and which inputs were ignored so callers can map it to their surface's
+ * failure envelope (MCP `fail`, agent `{ success: false }`).
+ */
+export declare class SilentDropError extends Error {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly dropped: string[];
+    constructor(entityType: string, entityId: string, dropped: string[]);
+}
+/**
+ * Thrown when a whole-body `update_entity` would remove embedded asset
+ * references (image/attachment embeds: `![[Foo.png]]` transclusions or
+ * `![alt](/api/assets/…)` markdown images) that are present in the entity's
+ * CURRENT body but absent from the submitted content.
+ *
+ * This is the guard for the silent-image-loss incident: `get_entity` reads
+ * the last-persisted disk body, which can lag the live editor (a user's
+ * freshly-placed image lives in the Y.Doc before autosave commits it). An
+ * agent that fetched stale content, edited text, and resent the whole body
+ * would drop those embeds — and because asset binaries live outside git,
+ * the lost references aren't recoverable from history. We refuse the write
+ * (no disk mutation happens) unless the caller explicitly opts in.
+ *
+ * Carries the dropped references so callers can map it to their surface's
+ * conflict envelope and tell the agent exactly what to preserve.
+ */
+export declare class DroppedAssetError extends Error {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly dropped: string[];
+    constructor(entityType: string, entityId: string, dropped: string[]);
+}
+/** Minimal graph surface diagnosedUpdate needs. */
+export interface DiagnosedUpdateGraph {
+    get(entityType: EntityType, entityId: string): EntityFile;
+    update(options: UpdateEntityOptions): Promise<EntityFile>;
+    /** Live editor body when a seeded Y.Doc is open, else null. Optional so
+     *  coordinator-less test/CLI graphs satisfy the interface; the asset-drop
+     *  guard falls back to the on-disk body when it's absent. */
+    getLiveBody?(entityType: EntityType, entityId: string): string | null;
+}
+export interface DiagnosedUpdateResult {
+    entity: EntityFile;
+    frontmatter_changed: boolean;
+    content_changed: boolean;
+    noop: boolean;
+    /** Post-commit broadcast disposition (null on the non-coordinator path). */
+    broadcast: BodyWriteResult['broadcast'] | null;
+}
+/**
+ * Run graph.update with the c6ef9297 diagnostic contract: snapshot before,
+ * update, then report whether frontmatter / content actually changed.
+ * Throws {@link SilentDropError} when the caller intended a change that
+ * produced no diff. Captures the body-write broadcast disposition.
+ *
+ * `inputs` are the caller's RAW intent (pre-payload-prep) — used only to
+ * decide whether a no-op was actually a silent drop. graph.get may throw
+ * (entity not found); callers' existing try/catch surfaces it.
+ */
+export declare function diagnosedUpdate(graph: DiagnosedUpdateGraph, options: UpdateEntityOptions, inputs: {
+    data?: Record<string, unknown>;
+    content?: string;
+}, guard?: {
+    allowAssetRemoval?: boolean;
+}): Promise<DiagnosedUpdateResult>;