studiograph 1.3.48-next.230 → 1.3.48-next.231

package/dist/core/field-library.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Field library mutation helpers
+ *
+ * Pure, framework-free functions that add / edit / remove a reusable custom
+ * field definition on a WorkspaceConfig. They return a new config object (the
+ * input is never mutated) so the HTTP layer can persist the result through
+ * `Workspace.writeConfig()`.
+ *
+ * Deliberately independent of SchemaRegistry / Zod entity validation: the
+ * field library is *soft* metadata (it drives the picker + agent awareness),
+ * not an enforced schema. Applying a field to an entry is an ordinary
+ * frontmatter write elsewhere; nothing here touches entity validation.
+ *
+ * Identity is `key`, global across the workspace (one `phase` everywhere).
+ * Editing options ripples to every entry using the field; existing entry
+ * values are never touched (removal is non-destructive — orphaned values stay
+ * on disk and simply stop being offered).
+ */
+import { type CustomFieldDef, type WorkspaceConfig } from './types.js';
+/** A mutation that fails a precondition (not found, collision, bad shape). */
+export declare class FieldLibraryError extends Error {
+    /** Stable machine code so the route maps to a status without string-matching. */
+    code: 'key_exists' | 'key_not_found' | 'invalid_field';
+    constructor(message: string, 
+    /** Stable machine code so the route maps to a status without string-matching. */
+    code: 'key_exists' | 'key_not_found' | 'invalid_field');
+}
+/** Current field library (empty when none defined). */
+export declare function getFieldLibrary(config: WorkspaceConfig): CustomFieldDef[];
+/** Look up one definition by key. */
+export declare function getFieldDef(config: WorkspaceConfig, key: string): CustomFieldDef | undefined;
+/**
+ * Validate a field definition's shape. Enforces the key shape and, for select
+ * fields, a non-empty list of unique, non-empty options. Throws
+ * FieldLibraryError on failure. Returns the parsed definition.
+ */
+export declare function validateFieldDef(input: unknown): CustomFieldDef;
+/**
+ * Add a new field definition. Returns a new WorkspaceConfig.
+ * Rejects a key already used by another definition.
+ */
+export declare function addFieldDef(config: WorkspaceConfig, input: {
+    key: string;
+    label?: string;
+    type?: 'select';
+    options: string[];
+    created_by?: string;
+}): WorkspaceConfig;
+/**
+ * Update an existing definition's options and/or label. The key is the
+ * identity and is not changed (renaming a key = add + remove, since it would
+ * orphan existing usages). Returns a new WorkspaceConfig.
+ */
+export declare function updateFieldDef(config: WorkspaceConfig, key: string, patch: {
+    options?: string[];
+    label?: string;
+}): WorkspaceConfig;
+/**
+ * Remove a definition from the library. Returns a new WorkspaceConfig.
+ * Non-destructive to entries — any stored values stay in their frontmatter.
+ */
+export declare function removeFieldDef(config: WorkspaceConfig, key: string): WorkspaceConfig;

package/dist/core/field-library.js

@@ -0,0 +1,129 @@
+/**
+ * Field library mutation helpers
+ *
+ * Pure, framework-free functions that add / edit / remove a reusable custom
+ * field definition on a WorkspaceConfig. They return a new config object (the
+ * input is never mutated) so the HTTP layer can persist the result through
+ * `Workspace.writeConfig()`.
+ *
+ * Deliberately independent of SchemaRegistry / Zod entity validation: the
+ * field library is *soft* metadata (it drives the picker + agent awareness),
+ * not an enforced schema. Applying a field to an entry is an ordinary
+ * frontmatter write elsewhere; nothing here touches entity validation.
+ *
+ * Identity is `key`, global across the workspace (one `phase` everywhere).
+ * Editing options ripples to every entry using the field; existing entry
+ * values are never touched (removal is non-destructive — orphaned values stay
+ * on disk and simply stop being offered).
+ */
+import { CustomFieldDefSchema } from './types.js';
+/** A mutation that fails a precondition (not found, collision, bad shape). */
+export class FieldLibraryError extends Error {
+    code;
+    constructor(message, 
+    /** Stable machine code so the route maps to a status without string-matching. */
+    code) {
+        super(message);
+        this.code = code;
+        this.name = 'FieldLibraryError';
+    }
+}
+/** Field key shape: lowercase, snake_case, must start with a letter. Mirrors
+ *  the client's `normalizedKey` normalization. */
+const KEY_RE = /^[a-z][a-z0-9_]*$/;
+/** Current field library (empty when none defined). */
+export function getFieldLibrary(config) {
+    return config.field_library ?? [];
+}
+/** Look up one definition by key. */
+export function getFieldDef(config, key) {
+    return getFieldLibrary(config).find(f => f.key === key);
+}
+/**
+ * Validate a field definition's shape. Enforces the key shape and, for select
+ * fields, a non-empty list of unique, non-empty options. Throws
+ * FieldLibraryError on failure. Returns the parsed definition.
+ */
+export function validateFieldDef(input) {
+    const parsed = CustomFieldDefSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new FieldLibraryError(`Invalid field definition: ${parsed.error.issues.map(i => i.message).join('; ')}`, 'invalid_field');
+    }
+    const def = parsed.data;
+    if (!KEY_RE.test(def.key)) {
+        throw new FieldLibraryError(`Field key "${def.key}" must be lowercase snake_case and start with a letter`, 'invalid_field');
+    }
+    validateOptions(def.options);
+    return def;
+}
+/** Shared option-list validation (non-empty, no blanks, unique). */
+function validateOptions(options) {
+    if (options.length === 0) {
+        throw new FieldLibraryError('A Select field needs at least one option', 'invalid_field');
+    }
+    if (options.some(v => v.trim() === '')) {
+        throw new FieldLibraryError('Select options cannot be empty', 'invalid_field');
+    }
+    if (new Set(options).size !== options.length) {
+        throw new FieldLibraryError('Select options must be unique', 'invalid_field');
+    }
+}
+/** Deep-clone the library so callers never mutate the live config. */
+function cloneLibrary(config) {
+    return structuredClone(config.field_library ?? []);
+}
+/**
+ * Add a new field definition. Returns a new WorkspaceConfig.
+ * Rejects a key already used by another definition.
+ */
+export function addFieldDef(config, input) {
+    const def = validateFieldDef({
+        key: input.key,
+        type: 'select',
+        options: input.options,
+        ...(input.label !== undefined ? { label: input.label } : {}),
+        ...(input.created_by !== undefined ? { created_by: input.created_by } : {}),
+        created_at: new Date().toISOString(),
+    });
+    if (getFieldDef(config, def.key)) {
+        throw new FieldLibraryError(`A field named "${def.key}" already exists`, 'key_exists');
+    }
+    const library = [...cloneLibrary(config), def];
+    return { ...config, field_library: library };
+}
+/**
+ * Update an existing definition's options and/or label. The key is the
+ * identity and is not changed (renaming a key = add + remove, since it would
+ * orphan existing usages). Returns a new WorkspaceConfig.
+ */
+export function updateFieldDef(config, key, patch) {
+    const current = getFieldDef(config, key);
+    if (!current) {
+        throw new FieldLibraryError(`No field named "${key}"`, 'key_not_found');
+    }
+    if (patch.options !== undefined)
+        validateOptions(patch.options);
+    const next = {
+        ...current,
+        ...(patch.options !== undefined ? { options: patch.options } : {}),
+        ...(patch.label !== undefined ? { label: patch.label } : {}),
+    };
+    const library = cloneLibrary(config).map(f => (f.key === key ? next : f));
+    return { ...config, field_library: library };
+}
+/**
+ * Remove a definition from the library. Returns a new WorkspaceConfig.
+ * Non-destructive to entries — any stored values stay in their frontmatter.
+ */
+export function removeFieldDef(config, key) {
+    if (!getFieldDef(config, key)) {
+        throw new FieldLibraryError(`No field named "${key}"`, 'key_not_found');
+    }
+    const library = cloneLibrary(config).filter(f => f.key !== key);
+    // Drop the array entirely when it empties, to keep workspace.json tidy.
+    const next = { ...config, field_library: library };
+    if (library.length === 0)
+        delete next.field_library;
+    return next;
+}
+//# sourceMappingURL=field-library.js.map

package/dist/core/field-library.js.map

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

package/dist/mcp/comment-virtual-entity.d.ts

@@ -0,0 +1,36 @@
+import type { CommentService } from '../services/comment-service.js';
+/**
+ * Comments live in SQLite for throughput, but agents should see them as
+ * first-class typed entities just like notes, projects, etc. This adapter
+ * shapes a Comment row into the same `{ id, entityType, data, content }`
+ * envelope that file-backed entities use, so generic MCP tools (`get_entity`,
+ * `list_entities`, `find_related`) can return comments without per-type
+ * branches in the tool code itself.
+ *
+ * The shape mirrors what `wm.getGraph(repo).get(...)` returns from
+ * filesystem entities: `id` is the comment_id (used in MCP URIs), `entityType`
+ * is the literal ‘comment’, `data` is frontmatter-flat with comment metadata,
+ * and `content` is the comment body.
+ */
+export interface VirtualEntityEnvelope {
+    id: string;
+    entityType: 'comment';
+    data: Record<string, unknown>;
+    document: {
+        content: string;
+        wikilinks: string[];
+    };
+}
+export declare function getComment(commentService: CommentService, commentId: string): VirtualEntityEnvelope | null;
+export declare function listComments(commentService: CommentService, opts?: {
+    repo?: string;
+    entryType?: string;
+    entryId?: string;
+    resolved?: boolean;
+    limit?: number;
+}): VirtualEntityEnvelope[];
+/**
+ * Comments anchored to a given entry — exposed as backlinks of that entry
+ * so `find_related` includes them naturally.
+ */
+export declare function findRelatedComments(commentService: CommentService, repo: string, entityType: string, entityId: string): VirtualEntityEnvelope[];

package/dist/mcp/comment-virtual-entity.js

@@ -0,0 +1,71 @@
+import { parseCellAnchor } from '../core/cell-anchor.js';
+function toEnvelope(c) {
+    // For dataset cell comments the anchor is JSON in anchor_relpos — surface
+    // the column + row snapshot so an agent reading the comment as an entity can
+    // locate the cell, not just see the bare cell value.
+    const cell = parseCellAnchor(c.anchorRelpos);
+    return {
+        id: c.commentId,
+        entityType: 'comment',
+        data: {
+            entity_type: 'comment',
+            entity_id: c.commentId,
+            created_at: c.createdAt,
+            updated_at: c.updatedAt ?? c.createdAt,
+            created_by: c.authorDisplayName,
+            updated_by: c.authorDisplayName,
+            // Comment-specific fields. Naming matches the SQL schema for
+            // consistency with the public REST API.
+            repo: c.repo,
+            entry_type: c.entryType,
+            entry_id: c.entryId,
+            thread_id: c.threadId,
+            parent_id: c.parentId,
+            author_user_id: c.authorUserId,
+            author_role: c.authorRole,
+            anchor_quote: c.anchorQuote,
+            ...(cell
+                ? {
+                    anchor_cell: {
+                        column: cell.headerName,
+                        column_index: cell.columnIndex,
+                        ...(cell.rowCells ? { row_cells: cell.rowCells } : {}),
+                    },
+                }
+                : {}),
+            resolved_at: c.resolvedAt,
+            resolved_by_user_id: c.resolvedByUserId,
+            edited: c.edited === 1,
+            mentions: c.mentions.map(m => m.handle),
+        },
+        document: { content: c.body, wikilinks: extractWikilinks(c.body) },
+    };
+}
+const WIKILINK_RE = /\[\[([^\]|#]+)(?:\|[^\]]+)?\]\]/g;
+function extractWikilinks(body) {
+    const out = [];
+    for (const match of body.matchAll(WIKILINK_RE)) {
+        if (match[1])
+            out.push(match[1].trim());
+    }
+    return out;
+}
+export function getComment(commentService, commentId) {
+    const c = commentService.getById(commentId);
+    if (!c || c.deletedAt)
+        return null;
+    return toEnvelope(c);
+}
+export function listComments(commentService, opts = {}) {
+    return commentService.list(opts).map(toEnvelope);
+}
+/**
+ * Comments anchored to a given entry — exposed as backlinks of that entry
+ * so `find_related` includes them naturally.
+ */
+export function findRelatedComments(commentService, repo, entityType, entityId) {
+    return commentService
+        .list({ repo, entryType: entityType, entryId: entityId })
+        .map(toEnvelope);
+}
+//# sourceMappingURL=comment-virtual-entity.js.map

package/dist/mcp/comment-virtual-entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-virtual-entity.js","sourceRoot":"","sources":["../../src/mcp/comment-virtual-entity.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/field-library-api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Field Library API routes
+ *
+ * CRUD over the workspace's reusable custom field definitions (the field
+ * library). A definition is *soft* metadata — it drives the field picker and
+ * agent awareness, but it never feeds SchemaRegistry, so applying a field is
+ * an ordinary entity frontmatter write and an off-list value is never
+ * rejected here.
+ *
+ * Auth: any authenticated member (no owner gate) — the global auth hook
+ * already rejects unauthenticated callers when users exist. Open mode / API
+ * key are admin-equivalent (no req.user), same as other routes.
+ *
+ * Persistence mirrors config-api: Workspace.writeConfig(next) →
+ * workspaceManager.reloadConfig() (re-reads workspace.json into the live
+ * in-memory config). No SchemaRegistry rebuild is needed — the library is not
+ * compiled into Zod.
+ *
+ *   GET    /api/field-library
+ *   POST   /api/field-library
+ *   PUT    /api/field-library/:key
+ *   DELETE /api/field-library/:key
+ *   GET    /api/field-library/:key/usage?value=
+ */
+import type { FastifyInstance } from 'fastify';
+import type { WorkspaceManager } from '../../core/workspace-manager.js';
+import type { AuthService } from '../../services/auth-service.js';
+export declare function registerFieldLibraryApiRoutes(fastify: FastifyInstance, workspaceManager: WorkspaceManager, _authService: AuthService): Promise<void>;

package/dist/server/routes/field-library-api.js

@@ -0,0 +1,126 @@
+/**
+ * Field Library API routes
+ *
+ * CRUD over the workspace's reusable custom field definitions (the field
+ * library). A definition is *soft* metadata — it drives the field picker and
+ * agent awareness, but it never feeds SchemaRegistry, so applying a field is
+ * an ordinary entity frontmatter write and an off-list value is never
+ * rejected here.
+ *
+ * Auth: any authenticated member (no owner gate) — the global auth hook
+ * already rejects unauthenticated callers when users exist. Open mode / API
+ * key are admin-equivalent (no req.user), same as other routes.
+ *
+ * Persistence mirrors config-api: Workspace.writeConfig(next) →
+ * workspaceManager.reloadConfig() (re-reads workspace.json into the live
+ * in-memory config). No SchemaRegistry rebuild is needed — the library is not
+ * compiled into Zod.
+ *
+ *   GET    /api/field-library
+ *   POST   /api/field-library
+ *   PUT    /api/field-library/:key
+ *   DELETE /api/field-library/:key
+ *   GET    /api/field-library/:key/usage?value=
+ */
+import { Workspace } from '../../core/workspace.js';
+import { addFieldDef, updateFieldDef, removeFieldDef, getFieldDef, getFieldLibrary, FieldLibraryError, } from '../../core/field-library.js';
+import { reqUser } from './graph-api-access.js';
+function mapError(err) {
+    switch (err.code) {
+        case 'key_exists': return { status: 409, code: err.code };
+        case 'key_not_found': return { status: 404, code: err.code };
+        case 'invalid_field': return { status: 400, code: err.code };
+        default: return { status: 400, code: 'invalid_field' };
+    }
+}
+export async function registerFieldLibraryApiRoutes(fastify, workspaceManager, _authService) {
+    /** Persist a config mutation: write workspace.json + refresh the live config. */
+    async function persist(next) {
+        const workspace = new Workspace(workspaceManager.getWorkspacePath());
+        workspace.writeConfig(next);
+        workspaceManager.reloadConfig();
+    }
+    // GET /api/field-library — list all definitions.
+    fastify.get('/api/field-library', async (_req, reply) => {
+        return reply.send({ fields: getFieldLibrary(workspaceManager.getConfig()) });
+    });
+    // POST /api/field-library — define a new field.
+    fastify.post('/api/field-library', async (req, reply) => {
+        const { key, label, options } = req.body ?? {};
+        try {
+            const next = addFieldDef(workspaceManager.getConfig(), {
+                key,
+                options,
+                ...(label !== undefined ? { label } : {}),
+                ...(reqUser(req)?.handle ? { created_by: reqUser(req).handle } : {}),
+            });
+            await persist(next);
+        }
+        catch (err) {
+            if (err instanceof FieldLibraryError) {
+                const { status, code } = mapError(err);
+                return reply.status(status).send({ code, error: err.message });
+            }
+            throw err;
+        }
+        return reply.send({ ok: true, fields: getFieldLibrary(workspaceManager.getConfig()) });
+    });
+    // PUT /api/field-library/:key — edit options/label. Returns affected-entry
+    // counts for any option values dropped by the edit (orphan warning).
+    fastify.put('/api/field-library/:key', async (req, reply) => {
+        const { key } = req.params;
+        const body = req.body ?? {};
+        const before = getFieldDef(workspaceManager.getConfig(), key);
+        const affected = {};
+        if (before?.options && Array.isArray(body.options)) {
+            const nextSet = new Set(body.options);
+            for (const v of before.options) {
+                if (!nextSet.has(v))
+                    affected[v] = workspaceManager.countEntitiesWithFieldValue(key, v);
+            }
+        }
+        try {
+            const next = updateFieldDef(workspaceManager.getConfig(), key, {
+                ...(body.options !== undefined ? { options: body.options } : {}),
+                ...(body.label !== undefined ? { label: body.label } : {}),
+            });
+            await persist(next);
+        }
+        catch (err) {
+            if (err instanceof FieldLibraryError) {
+                const { status, code } = mapError(err);
+                return reply.status(status).send({ code, error: err.message });
+            }
+            throw err;
+        }
+        return reply.send({ ok: true, fields: getFieldLibrary(workspaceManager.getConfig()), affected });
+    });
+    // DELETE /api/field-library/:key — remove the definition. Entry values are
+    // left on disk. Returns the count of entries that still held the field.
+    fastify.delete('/api/field-library/:key', async (req, reply) => {
+        const { key } = req.params;
+        const affected = workspaceManager.countEntitiesWithFieldValue(key);
+        try {
+            const next = removeFieldDef(workspaceManager.getConfig(), key);
+            await persist(next);
+        }
+        catch (err) {
+            if (err instanceof FieldLibraryError) {
+                const { status, code } = mapError(err);
+                return reply.status(status).send({ code, error: err.message });
+            }
+            throw err;
+        }
+        return reply.send({ ok: true, fields: getFieldLibrary(workspaceManager.getConfig()), affected });
+    });
+    // GET /api/field-library/:key/usage?value= — entry counts behind the
+    // orphan-warning before an option/field removal.
+    fastify.get('/api/field-library/:key/usage', async (req, reply) => {
+        const { key } = req.params;
+        const { value } = req.query;
+        const total = workspaceManager.countEntitiesWithFieldValue(key);
+        const forValue = value !== undefined ? workspaceManager.countEntitiesWithFieldValue(key, value) : undefined;
+        return reply.send({ total, ...(forValue !== undefined ? { value, count: forValue } : {}) });
+    });
+}
+//# sourceMappingURL=field-library-api.js.map

package/dist/server/routes/field-library-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-library-api.js","sourceRoot":"","sources":["../../../src/server/routes/field-library-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGpD,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,eAAe,EACf,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,SAAS,QAAQ,CAAC,GAAsB;IACtC,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,YAAY,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1D,KAAK,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7D,KAAK,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7D,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IACzD,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,OAAwB,EACxB,gBAAkC,EAClC,YAAyB;IAEzB,iFAAiF;IACjF,KAAK,UAAU,OAAO,CAAC,IAAmD;QACxE,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACrE,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5B,gBAAgB,CAAC,YAAY,EAAE,CAAC;IAClC,CAAC;IAED,iDAAiD;IACjD,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACtD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,gBAAgB,CAAC,SAAS,EAAS,CAAC,EAAE,CAAC,CAAC;IACtF,CAAC,CAAC,CAAC;IAEH,gDAAgD;IAChD,OAAO,CAAC,IAAI,CAET,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAC5C,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,IAAK,EAAU,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,WAAW,CAAC,gBAAgB,CAAC,SAAS,EAAS,EAAE;gBAC5D,GAAG;gBACH,OAAO;gBACP,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,CAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtE,CAAC,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;gBACrC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACvC,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,gBAAgB,CAAC,SAAS,EAAS,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,qEAAqE;IACrE,OAAO,CAAC,GAAG,CAGR,yBAAyB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QACjD,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QAE5B,MAAM,MAAM,GAAG,WAAW,CAAC,gBAAgB,CAAC,SAAS,EAAS,EAAE,GAAG,CAAC,CAAC;QACrE,MAAM,QAAQ,GAA2B,EAAE,CAAC;QAC5C,IAAI,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,2BAA2B,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,cAAc,CAAC,gBAAgB,CAAC,SAAS,EAAS,EAAE,GAAG,EAAE;gBACpE,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D,CAAC,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;gBACrC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACvC,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,gBAAgB,CAAC,SAAS,EAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1G,CAAC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAA8B,yBAAyB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAC1F,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAC3B,MAAM,QAAQ,GAAG,gBAAgB,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,cAAc,CAAC,gBAAgB,CAAC,SAAS,EAAS,EAAE,GAAG,CAAC,CAAC;YACtE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;gBACrC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;gBACvC,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,gBAAgB,CAAC,SAAS,EAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1G,CAAC,CAAC,CAAC;IAEH,qEAAqE;IACrE,iDAAiD;IACjD,OAAO,CAAC,GAAG,CAGR,+BAA+B,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QACvD,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAC3B,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC;QAC5B,MAAM,KAAK,GAAG,gBAAgB,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,2BAA2B,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5G,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server/routes/graph-api.js

@@ -388,6 +388,30 @@ export async function registerGraphApiRoutes(fastify, workspaceManager, authServ
         }
         return reply.send(entity);
     });
+    // GET /api/repos/:repo/entities/:type/:id/source — download the raw
+    // markdown file (frontmatter + body verbatim, exactly as on disk). For
+    // artifacts the body IS the embedded bundle JSON, so the download is a
+    // portable single-file copy of the whole entry. Read-gated like every
+    // other entity read; serialization fidelity comes from serving the disk
+    // bytes rather than re-emitting parsed frontmatter.
+    fastify.get('/api/repos/:repo/entities/:type/:id/source', async (req, reply) => {
+        const { repo, type, id } = req.params;
+        // Access enforced by graphForRead (WorkspaceAccessService).
+        const graph = graphForRead(req, reply, repo);
+        if (!graph)
+            return;
+        const filePath = graph.getEntityFilePath(type, id);
+        if (!filePath || !existsSync(filePath)) {
+            return reply.status(404).send({ error: `Entity not found: ${type}/${id}` });
+        }
+        const raw = readFileSync(filePath);
+        // Entity ids are kebab-case slugs (ASCII-safe), so the quoted filename
+        // needs no RFC 5987 escaping.
+        reply.header('Content-Disposition', `attachment; filename="${id}.md"`);
+        reply.header('Content-Type', 'text/markdown; charset=utf-8');
+        reply.header('X-Content-Type-Options', 'nosniff');
+        return reply.send(raw);
+    });
     // GET /api/repos/:repo/entities/:type/:id/history — entity commit history
     fastify.get('/api/repos/:repo/entities/:type/:id/history', async (req, reply) => {
         const { repo, type, id } = req.params;