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

package/dist/core/entity-body-templates.js

@@ -0,0 +1,53 @@
+/**
+ * Built-in markdown body templates for each canonical entity type.
+ *
+ * Shared between:
+ *   - `src/core/schema-registry.ts` — server-side default-body lookup
+ *   - `web/src/lib/components/layout/Sidebar.svelte` — New Entry picker
+ *
+ * Previously the Sidebar shipped its own copy of this map, which drifted
+ * from the server version (e.g. `deck:` was briefly slides-renderer
+ * markup on the frontend while the server had a renderer-agnostic
+ * outline). Keeping one source avoids that trap.
+ *
+ * Pure data, no runtime deps — safe to import from the web bundle via
+ * the `@core/entity-body-templates` alias.
+ */
+export const BUILTIN_BODY_TEMPLATES = {
+    // CRM
+    person: '## Bio\n\n## Notes\n\n',
+    organization: '## Profile\n\n## Notes\n\n',
+    position: '## Responsibilities\n\n## Requirements\n\n## Notes\n\n',
+    deal: '## Opportunity\n\n## Scope\n\n## Notes\n\n',
+    // PM
+    project: '## Overview\n\n## Deliverables\n\n## Notes\n\n',
+    event: '## Summary\n\n## Notes\n\n## Action Items\n\n',
+    task: '## Description\n\n## Notes\n\n',
+    deliverable: '## Overview\n\n## Scope\n\n## Notes\n\n',
+    // KM — authored
+    document: '## Overview\n\n## Details\n\n',
+    deck: '## Outline\n\n## Slides\n\n## Speaker Notes\n\n',
+    publication: '## Content\n\n## Distribution\n\n## Notes\n\n',
+    'case-study': '## Objective\n\n## Solution\n\n## Outcome\n\n## Team\n\n',
+    service: '## Overview\n\n## Steps\n\n## Best Practices\n\n**Do:**\n-\n\n**Don\'t:**\n-\n\n## Notes\n\n',
+    // skill: the body IS the prompt content the agent loads at runtime. The
+    // four-section scaffold mirrors Anthropic's recommended SKILL.md shape
+    // (when to trigger, how to run, hard constraints, reference material)
+    // minus the redundant h1 (title lives in frontmatter name).
+    skill: '## When to use\n- Trigger conditions\n- Scope boundaries\n\n## Workflow\n1. Step one\n2. Step two\n3. Step three\n\n## Rules\n- Hard requirements\n- Constraints\n- Anti-patterns\n\n## References\n- File paths\n- Examples\n- Templates\n',
+    // Capture
+    reference: '## Description\n\n## Notes\n\n',
+    // dataset body is CSV, not markdown. Start a picker-created dataset with a
+    // 3×3 grid (header row + three empty rows) so there's a usable shape to edit
+    // immediately. The header row IS the column list — there's no separate
+    // schema. The empty `,,` rows survive the grid's skipEmptyLines parse.
+    dataset: 'Column 1,Column 2,Column 3\n,,\n,,\n,,\n',
+};
+/**
+ * Look up the default body template for a canonical type.
+ * Returns null when the type has no template (e.g. `note`).
+ */
+export function getBuiltinBodyTemplate(entityType) {
+    return BUILTIN_BODY_TEMPLATES[entityType] ?? null;
+}
+//# sourceMappingURL=entity-body-templates.js.map

package/dist/core/entity-body-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-body-templates.js","sourceRoot":"","sources":["../../src/core/entity-body-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC5D,MAAM;IACN,MAAM,EAAW,wBAAwB;IACzC,YAAY,EAAK,4BAA4B;IAC7C,QAAQ,EAAS,wDAAwD;IACzE,IAAI,EAAa,4CAA4C;IAE7D,KAAK;IACL,OAAO,EAAU,gDAAgD;IACjE,KAAK,EAAY,+CAA+C;IAChE,IAAI,EAAa,gCAAgC;IACjD,WAAW,EAAM,yCAAyC;IAE1D,gBAAgB;IAChB,QAAQ,EAAS,+BAA+B;IAChD,IAAI,EAAa,iDAAiD;IAClE,WAAW,EAAM,+CAA+C;IAChE,YAAY,EAAK,0DAA0D;IAC3E,OAAO,EAAU,8FAA8F;IAC/G,wEAAwE;IACxE,uEAAuE;IACvE,sEAAsE;IACtE,4DAA4D;IAC5D,KAAK,EAAY,6OAA6O;IAE9P,UAAU;IACV,SAAS,EAAQ,gCAAgC;IACjD,2EAA2E;IAC3E,6EAA6E;IAC7E,uEAAuE;IACvE,uEAAuE;IACvE,OAAO,EAAU,0CAA0C;CAC5D,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,OAAO,sBAAsB,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AACpD,CAAC"}

package/dist/core/entity-types-catalog.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Curated entity-type catalog for Studiograph.
+ *
+ * The full canonical schema set lives in `validation.ts` (ENTITY_SCHEMAS).
+ * This file exposes two cross-cutting concerns:
+ *
+ * 1. `DEFAULT_BASIC_ENTITY_TYPES` — the small default set every fresh
+ *    workspace surfaces in the New Entry modal's "basic" tier. The tier
+ *    grows for each user as entries of other curated types appear in
+ *    folders that user can access (see the picker in
+ *    web/src/lib/components/entity/NewEntryTypePicker.svelte). There is no
+ *    persistent per-workspace "active set" — visibility is derived from
+ *    graph presence + folder permissions.
+ *
+ * 2. `CURATED_ENTITY_TYPE_DESCRIPTIONS` — short one-line descriptions for
+ *    every canonical type. Used by the agent system prompt, tool reference,
+ *    and the picker's detail pane.
+ *
+ * This module is pure data — no runtime dependencies on Node APIs or Zod —
+ * so it is safe to import from the web bundle via the
+ * `@core/entity-types-catalog` alias.
+ */
+/**
+ * Default "basic" tier for a fresh workspace. Just the three capture
+ * primitives — the answer to "what do you want to create right now?".
+ * Project / person / organization are organizational types that surface
+ * automatically via the presence-based rule the moment someone creates
+ * their first one. The picker augments this default with any curated
+ * types already present in folders the user can access.
+ */
+export declare const DEFAULT_BASIC_ENTITY_TYPES: readonly ["note", "event", "task"];
+export type DefaultBasicEntityType = typeof DEFAULT_BASIC_ENTITY_TYPES[number];
+export declare function isDefaultBasicEntityType(type: string): boolean;
+/**
+ * Notable fields for each canonical type — the ones worth surfacing in the
+ * New Entry picker's detail pane as "what this type captures" chips. Not a
+ * complete field list; that lives in the Zod schemas. Base fields
+ * (entity_type, entity_id, created_at, etc.) are never listed here.
+ *
+ * Labels are Title Case to match the user-facing property panel.
+ */
+export declare const CURATED_ENTITY_TYPE_FIELDS: Record<string, string[]>;
+export declare function getCuratedEntityTypeFields(type: string): readonly string[];
+/**
+ * One-line descriptions for every canonical entity type. Terse on purpose —
+ * full schema detail lives in validation.ts and is available on demand via
+ * the `get_entity_schema` tool.
+ */
+export declare const CURATED_ENTITY_TYPE_DESCRIPTIONS: Record<string, string>;
+/**
+ * The canonical list of curated entity types, in catalog order. Derived
+ * from CURATED_ENTITY_TYPE_DESCRIPTIONS so descriptions and the type list
+ * stay in sync without this module taking a Zod dependency.
+ */
+export declare const CURATED_ENTITY_TYPES: readonly string[];
+export declare function isCuratedEntityType(type: string): boolean;
+export declare function getCuratedEntityTypeDescription(type: string): string | undefined;
+/**
+ * Compute the "basic" tier of entity types for a given user:
+ * defaults ∪ curated types already present in folders the user can access.
+ * `presentTypes` comes from the permission-filtered /api/repos response —
+ * so this helper respects folder access for free. Non-curated types in
+ * `presentTypes` (e.g. workspace custom types) pass through unchanged.
+ */
+export declare function computeBasicEntityTypes(presentTypes: Iterable<string>): string[];

package/dist/core/entity-types-catalog.js

@@ -0,0 +1,140 @@
+/**
+ * Curated entity-type catalog for Studiograph.
+ *
+ * The full canonical schema set lives in `validation.ts` (ENTITY_SCHEMAS).
+ * This file exposes two cross-cutting concerns:
+ *
+ * 1. `DEFAULT_BASIC_ENTITY_TYPES` — the small default set every fresh
+ *    workspace surfaces in the New Entry modal's "basic" tier. The tier
+ *    grows for each user as entries of other curated types appear in
+ *    folders that user can access (see the picker in
+ *    web/src/lib/components/entity/NewEntryTypePicker.svelte). There is no
+ *    persistent per-workspace "active set" — visibility is derived from
+ *    graph presence + folder permissions.
+ *
+ * 2. `CURATED_ENTITY_TYPE_DESCRIPTIONS` — short one-line descriptions for
+ *    every canonical type. Used by the agent system prompt, tool reference,
+ *    and the picker's detail pane.
+ *
+ * This module is pure data — no runtime dependencies on Node APIs or Zod —
+ * so it is safe to import from the web bundle via the
+ * `@core/entity-types-catalog` alias.
+ */
+/**
+ * Default "basic" tier for a fresh workspace. Just the three capture
+ * primitives — the answer to "what do you want to create right now?".
+ * Project / person / organization are organizational types that surface
+ * automatically via the presence-based rule the moment someone creates
+ * their first one. The picker augments this default with any curated
+ * types already present in folders the user can access.
+ */
+export const DEFAULT_BASIC_ENTITY_TYPES = [
+    'note',
+    'event',
+    'task',
+];
+const DEFAULT_BASIC_SET = new Set(DEFAULT_BASIC_ENTITY_TYPES);
+export function isDefaultBasicEntityType(type) {
+    return DEFAULT_BASIC_SET.has(type);
+}
+/**
+ * Notable fields for each canonical type — the ones worth surfacing in the
+ * New Entry picker's detail pane as "what this type captures" chips. Not a
+ * complete field list; that lives in the Zod schemas. Base fields
+ * (entity_type, entity_id, created_at, etc.) are never listed here.
+ *
+ * Labels are Title Case to match the user-facing property panel.
+ */
+export const CURATED_ENTITY_TYPE_FIELDS = {
+    // CRM
+    person: ['Name', 'Role', 'Category', 'Status', 'Email', 'Location', 'Organization'],
+    organization: ['Name', 'Category', 'Status', 'Industry', 'Website'],
+    position: ['Name', 'Department', 'Category', 'Status'],
+    deal: ['Name', 'Client', 'Contact', 'Stage', 'Deal value', 'Start date', 'Close date'],
+    // PM
+    project: ['Name', 'Category', 'Project type', 'Client', 'Services', 'Status', 'Start date', 'End date'],
+    event: ['Name', 'Type', 'Attendees', 'Location', 'Start date', 'End date'],
+    task: ['Name', 'Status', 'Priority', 'Assignee', 'Phase', 'Start date', 'Due date'],
+    deliverable: ['Name', 'Project', 'Status', 'Phase', 'Start date', 'Due date'],
+    // KM — authored
+    document: ['Name', 'Category', 'Status'],
+    deck: ['Name', 'Audience', 'Status'],
+    publication: ['Name', 'Platform', 'Status', 'URL'],
+    'case-study': ['Name', 'Client', 'Services', 'Date range', 'Status'],
+    service: ['Name', 'Service id', 'Sprint', 'Depends on', 'Enables', 'Deliverables', 'Status'],
+    skill: ['Name', 'Description', 'Applies to'],
+    // Capture
+    note: ['Name'],
+    reference: ['Name', 'Source', 'Link'],
+    dataset: ['Name'],
+    material: ['Name', 'Category'],
+    // System
+    comment: ['Body', 'Anchor', 'Resolved'],
+};
+export function getCuratedEntityTypeFields(type) {
+    return CURATED_ENTITY_TYPE_FIELDS[type] ?? [];
+}
+/**
+ * One-line descriptions for every canonical entity type. Terse on purpose —
+ * full schema detail lives in validation.ts and is available on demand via
+ * the `get_entity_schema` tool.
+ */
+export const CURATED_ENTITY_TYPE_DESCRIPTIONS = {
+    // CRM
+    person: 'An individual — team member, client, or contact',
+    organization: 'A company, client, vendor, or partner',
+    position: 'A role or job description',
+    deal: 'A pre-project sales opportunity',
+    // PM
+    project: 'A client engagement or internal initiative',
+    event: 'A meeting, call, workshop, or other gathering',
+    task: 'An action item or to-do',
+    deliverable: 'A scoped output promised to a client',
+    // KM — authored
+    document: 'A proposal, contract, brief, memo, or report',
+    deck: 'A presentation or slide deck',
+    publication: 'Content published externally',
+    'case-study': 'A portfolio narrative',
+    service: 'An offering or methodology your team provides',
+    skill: 'Reusable agent instructions',
+    // Capture
+    note: 'A freeform note or thought',
+    reference: 'An external resource or piece of inspiration',
+    dataset: 'Structured tabular data',
+    material: 'A binary asset (image, design file, video, archive) wrapped as an entry',
+    // System
+    comment: 'A threaded comment anchored to an entry — questions, decisions, objections, approvals',
+};
+/**
+ * The canonical list of curated entity types, in catalog order. Derived
+ * from CURATED_ENTITY_TYPE_DESCRIPTIONS so descriptions and the type list
+ * stay in sync without this module taking a Zod dependency.
+ */
+export const CURATED_ENTITY_TYPES = Object.freeze(Object.keys(CURATED_ENTITY_TYPE_DESCRIPTIONS));
+const CURATED_ENTITY_TYPES_SET = new Set(CURATED_ENTITY_TYPES);
+export function isCuratedEntityType(type) {
+    return CURATED_ENTITY_TYPES_SET.has(type);
+}
+export function getCuratedEntityTypeDescription(type) {
+    return CURATED_ENTITY_TYPE_DESCRIPTIONS[type];
+}
+/**
+ * Compute the "basic" tier of entity types for a given user:
+ * defaults ∪ curated types already present in folders the user can access.
+ * `presentTypes` comes from the permission-filtered /api/repos response —
+ * so this helper respects folder access for free. Non-curated types in
+ * `presentTypes` (e.g. workspace custom types) pass through unchanged.
+ */
+export function computeBasicEntityTypes(presentTypes) {
+    const set = new Set(DEFAULT_BASIC_ENTITY_TYPES);
+    // Include every present type so workspace custom types also surface in
+    // the basic tier once they have at least one entry. Whitespace-only
+    // values are treated as absent — they can sneak in from stale API
+    // responses or test fixtures and would pollute the picker otherwise.
+    for (const t of presentTypes) {
+        if (t && t.trim().length > 0)
+            set.add(t);
+    }
+    return Array.from(set);
+}
+//# sourceMappingURL=entity-types-catalog.js.map

package/dist/core/entity-types-catalog.js.map

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

package/dist/core/folder-paths.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Folder path validation and normalization for nested folders within a repo.
+ *
+ * Folder paths are repo-relative POSIX strings (e.g. "clients/acme"). They never
+ * start or end with "/", and segments must be filesystem-safe. Empty string is
+ * the repo root.
+ *
+ * `folder_path` is derived from the file's location on disk at read time — it's
+ * not stored in frontmatter. That keeps the filesystem as the source of truth
+ * and avoids the rename-folder-must-update-N-files problem.
+ */
+export declare class InvalidFolderPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a single folder segment (one level of the path). Throws on:
+ * - empty string
+ * - leading/trailing whitespace or dots
+ * - path separators
+ * - reserved chars or names
+ */
+export declare function validateFolderSegment(name: string): void;
+/**
+ * Normalize a folder path: trim slashes, collapse repeats. Returns "" for root.
+ * Throws on `..` segments (prevents escaping the repo).
+ */
+export declare function normalizeFolderPath(path: string | undefined | null): string;
+/**
+ * Validate a full folder path (one or more segments joined by "/"). Returns
+ * the normalized form for convenience.
+ */
+export declare function validateFolderPath(path: string | undefined | null): string;
+/**
+ * Compute the parent folder path. Returns "" if already at root.
+ */
+export declare function parentFolderPath(path: string): string;
+/**
+ * Derive the folder_path of a file given its absolute path and the repo root.
+ * Returns "" if the file lives at the repo root.
+ */
+export declare function folderPathFromFile(filePath: string, repoPath: string): string;

package/dist/core/folder-paths.js

@@ -0,0 +1,95 @@
+/**
+ * Folder path validation and normalization for nested folders within a repo.
+ *
+ * Folder paths are repo-relative POSIX strings (e.g. "clients/acme"). They never
+ * start or end with "/", and segments must be filesystem-safe. Empty string is
+ * the repo root.
+ *
+ * `folder_path` is derived from the file's location on disk at read time — it's
+ * not stored in frontmatter. That keeps the filesystem as the source of truth
+ * and avoids the rename-folder-must-update-N-files problem.
+ */
+/** Reserved characters disallowed in any folder segment. */
+const RESERVED_CHARS = /[<>:"|?*\\]/;
+/** Names that are not valid folder segments (filesystem-reserved or special). */
+const RESERVED_NAMES = new Set(['.', '..', '.git', '.studiograph', '.gitkeep']);
+export class InvalidFolderPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidFolderPathError';
+    }
+}
+/**
+ * Validate a single folder segment (one level of the path). Throws on:
+ * - empty string
+ * - leading/trailing whitespace or dots
+ * - path separators
+ * - reserved chars or names
+ */
+export function validateFolderSegment(name) {
+    if (!name || typeof name !== 'string') {
+        throw new InvalidFolderPathError('Folder segment must be a non-empty string');
+    }
+    if (name !== name.trim()) {
+        throw new InvalidFolderPathError(`Folder segment cannot have leading or trailing whitespace: "${name}"`);
+    }
+    if (name.startsWith('.') || name.endsWith('.')) {
+        throw new InvalidFolderPathError(`Folder segment cannot start or end with "." : "${name}"`);
+    }
+    if (name.includes('/')) {
+        throw new InvalidFolderPathError(`Folder segment cannot contain "/" : "${name}"`);
+    }
+    if (RESERVED_CHARS.test(name)) {
+        throw new InvalidFolderPathError(`Folder segment contains reserved characters: "${name}"`);
+    }
+    if (RESERVED_NAMES.has(name)) {
+        throw new InvalidFolderPathError(`Folder segment uses a reserved name: "${name}"`);
+    }
+}
+/**
+ * Normalize a folder path: trim slashes, collapse repeats. Returns "" for root.
+ * Throws on `..` segments (prevents escaping the repo).
+ */
+export function normalizeFolderPath(path) {
+    if (!path)
+        return '';
+    // Strip leading/trailing slashes, split, drop empties, validate each.
+    const segments = path
+        .replace(/^\/+|\/+$/g, '')
+        .split('/')
+        .filter(s => s.length > 0);
+    for (const segment of segments) {
+        validateFolderSegment(segment);
+    }
+    return segments.join('/');
+}
+/**
+ * Validate a full folder path (one or more segments joined by "/"). Returns
+ * the normalized form for convenience.
+ */
+export function validateFolderPath(path) {
+    return normalizeFolderPath(path);
+}
+/**
+ * Compute the parent folder path. Returns "" if already at root.
+ */
+export function parentFolderPath(path) {
+    const normalized = normalizeFolderPath(path);
+    if (!normalized)
+        return '';
+    const idx = normalized.lastIndexOf('/');
+    return idx === -1 ? '' : normalized.slice(0, idx);
+}
+/**
+ * Derive the folder_path of a file given its absolute path and the repo root.
+ * Returns "" if the file lives at the repo root.
+ */
+export function folderPathFromFile(filePath, repoPath) {
+    const normalizedRepo = repoPath.replace(/\/+$/, '');
+    if (!filePath.startsWith(normalizedRepo + '/'))
+        return '';
+    const rel = filePath.slice(normalizedRepo.length + 1);
+    const idx = rel.lastIndexOf('/');
+    return idx === -1 ? '' : rel.slice(0, idx);
+}
+//# sourceMappingURL=folder-paths.js.map

package/dist/core/folder-paths.js.map

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

package/dist/core/folder-sidecar.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-folder sidecar carrying an optional `display_name` override and a stable
+ * folder `id`. Lives inside the folder itself so it travels atomically with FS
+ * rename / move / cross-repo transfer — the same way an entity .md file's
+ * frontmatter travels with the file.
+ *
+ * The `id` is assigned eagerly in mutation paths (folder creation); reads never
+ * generate one. Callers that don't find an id fall back to a path-based key.
+ */
+export declare const FOLDER_SIDECAR = ".studiograph-folder.json";
+export interface FolderSidecarData {
+    display_name?: string;
+    id?: string;
+}
+export declare function folderSidecarPath(absDir: string): string;
+/**
+ * Read the full sidecar object for a folder, or null when the sidecar is
+ * absent / unreadable / malformed. Only the recognized fields are surfaced.
+ */
+export declare function readFolderSidecarData(absDir: string): FolderSidecarData | null;
+/** Read just the display_name override, or null. (Back-compat helper.) */
+export declare function readFolderSidecar(absDir: string): string | null;
+/** Read just the stable folder id, or null when unassigned. */
+export declare function readFolderSidecarId(absDir: string): string | null;
+/**
+ * Merge-safe write: reads the existing sidecar, applies the patch, and writes
+ * the result — so writing one field never clobbers the other. A field present
+ * in `patch` but empty/undefined is removed; a field absent from `patch` is
+ * left untouched. If the merge leaves the sidecar empty, the file is removed.
+ * Returns the sidecar path (for git staging), or null when the file was
+ * removed because nothing remained.
+ */
+export declare function writeFolderSidecarData(absDir: string, patch: FolderSidecarData): string | null;
+/** Write/merge a display_name override (preserves any existing id). */
+export declare function writeFolderSidecar(absDir: string, displayName: string): string;
+export declare function removeFolderSidecar(absDir: string): string | null;

package/dist/core/folder-sidecar.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Per-folder sidecar carrying an optional `display_name` override and a stable
+ * folder `id`. Lives inside the folder itself so it travels atomically with FS
+ * rename / move / cross-repo transfer — the same way an entity .md file's
+ * frontmatter travels with the file.
+ *
+ * The `id` is assigned eagerly in mutation paths (folder creation); reads never
+ * generate one. Callers that don't find an id fall back to a path-based key.
+ */
+export const FOLDER_SIDECAR = '.studiograph-folder.json';
+export function folderSidecarPath(absDir) {
+    return join(absDir, FOLDER_SIDECAR);
+}
+/**
+ * Read the full sidecar object for a folder, or null when the sidecar is
+ * absent / unreadable / malformed. Only the recognized fields are surfaced.
+ */
+export function readFolderSidecarData(absDir) {
+    const sidecarPath = folderSidecarPath(absDir);
+    if (!existsSync(sidecarPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(sidecarPath, 'utf-8'));
+        const data = {};
+        if (typeof parsed?.display_name === 'string' && parsed.display_name.trim()) {
+            data.display_name = parsed.display_name.trim();
+        }
+        if (typeof parsed?.id === 'string' && parsed.id.trim()) {
+            data.id = parsed.id.trim();
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read just the display_name override, or null. (Back-compat helper.) */
+export function readFolderSidecar(absDir) {
+    return readFolderSidecarData(absDir)?.display_name ?? null;
+}
+/** Read just the stable folder id, or null when unassigned. */
+export function readFolderSidecarId(absDir) {
+    return readFolderSidecarData(absDir)?.id ?? null;
+}
+/**
+ * Merge-safe write: reads the existing sidecar, applies the patch, and writes
+ * the result — so writing one field never clobbers the other. A field present
+ * in `patch` but empty/undefined is removed; a field absent from `patch` is
+ * left untouched. If the merge leaves the sidecar empty, the file is removed.
+ * Returns the sidecar path (for git staging), or null when the file was
+ * removed because nothing remained.
+ */
+export function writeFolderSidecarData(absDir, patch) {
+    const merged = { ...(readFolderSidecarData(absDir) ?? {}) };
+    if ('display_name' in patch) {
+        const dn = patch.display_name?.trim();
+        if (dn)
+            merged.display_name = dn;
+        else
+            delete merged.display_name;
+    }
+    if ('id' in patch) {
+        const id = patch.id?.trim();
+        if (id)
+            merged.id = id;
+        else
+            delete merged.id;
+    }
+    const sidecarPath = folderSidecarPath(absDir);
+    if (Object.keys(merged).length === 0) {
+        return removeFolderSidecar(absDir);
+    }
+    mkdirSync(absDir, { recursive: true });
+    writeFileSync(sidecarPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+    return sidecarPath;
+}
+/** Write/merge a display_name override (preserves any existing id). */
+export function writeFolderSidecar(absDir, displayName) {
+    // Non-null: a non-empty displayName always leaves the sidecar non-empty.
+    return writeFolderSidecarData(absDir, { display_name: displayName });
+}
+export function removeFolderSidecar(absDir) {
+    const sidecarPath = folderSidecarPath(absDir);
+    if (!existsSync(sidecarPath))
+        return null;
+    rmSync(sidecarPath, { force: true });
+    return sidecarPath;
+}
+//# sourceMappingURL=folder-sidecar.js.map

package/dist/core/folder-sidecar.js.map

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