studiograph 1.3.48-next.21 → 1.3.48-next.211

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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"}

package/dist/core/format-registry.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Format Registry — the single source of truth for how Studiograph ingests
+ * every file type.
+ *
+ * Framework-free and dependency-free (sits alongside `validation.ts` /
+ * `schema-registry.ts`), so it can be imported by server routes, services,
+ * the MCP layer, the CLI, and serialized to the web client over
+ * `GET /api/formats`. Every ingestion surface reads from here instead of
+ * maintaining its own parallel extension / MIME / accept list — that
+ * divergence (a stale `.xlsx`, a half-supported `.svg`, a PDF that becomes
+ * an asset on one path and a note on another) is exactly what this registry
+ * exists to kill.
+ *
+ * Each `FormatEntry` declares the full disposition of a format: how it's
+ * handled, whether the original is retained, what (if anything) it derives
+ * to, how it's indexed for search, and which extractor feeds that index.
+ * The fields are consumed incrementally across the phased refactor — P0 wires
+ * the routing (`handler`, `category`, `extractor`, `sanitize`) and the
+ * searchability contract (`indexAs`); later phases consume `deriveTo` /
+ * `derive` (conversions, P2), `extractor` for sidecars/captions (indexing,
+ * P3), `mimeTypes` (MCP presign, P4), and the serialized shape (client, P5).
+ *
+ * "Dependency-free" here means no npm packages / no framework — the Node
+ * `path` builtin is fine and shared with the rest of `src/core`.
+ */
+/** How a format is dispatched + what it ultimately becomes. */
+export type FormatCategory = 'direct-note' | 'direct-dataset' | 'asset-convertible' | 'asset' | 'bookmarks';
+/** Which server handler ingests the bytes. */
+export type FormatHandler = 'importDirect' | 'uploadAsset' | 'importBookmarks';
+/** The entity a convertible format derives to (entry-primary, D1). */
+export type FormatDeriveTo = 'note' | 'dataset' | 'reference' | null;
+/** When the derivation happens. */
+export type FormatDerive = 'inline' | 'deferred' | 'none';
+/**
+ * How the format feeds the search index.
+ * - `body`    — the entity body itself is the index text (notes, datasets).
+ * - `sidecar` — extracted text written to a `.studiograph/assets-text/` sidecar.
+ * - `caption` — vision caption + OCR text written to a sidecar.
+ * - `none`    — opaque; filename + frontmatter only (`indexable: false`).
+ */
+export type FormatIndexAs = 'body' | 'sidecar' | 'caption' | 'none';
+/** The extractor that produces index text for this format (null = none). */
+export type FormatExtractor = 'pdf' | 'docx' | 'xlsx' | 'image-caption' | null;
+export interface FormatEntry {
+    /** Lowercased, dot-prefixed extensions (`['.md']`). */
+    extensions: string[];
+    /** MIME types — drives the MCP presign allowlist (P4) + client hints. */
+    mimeTypes: string[];
+    category: FormatCategory;
+    /** Entry-primary: keep the original binary after deriving (D1). */
+    retainSource: boolean;
+    deriveTo: FormatDeriveTo;
+    derive: FormatDerive;
+    /** `'none'` ⇒ `indexable: false` in frontmatter. */
+    indexAs: FormatIndexAs;
+    handler: FormatHandler;
+    extractor: FormatExtractor;
+    /** Declarative upper bound (bytes). Not enforced in P0; wired later. */
+    maxBytes: number;
+    /** Bytes need sanitizing before they're stored/served (SVG XSS, D7). */
+    sanitize?: 'svg';
+    /**
+     * P0 transitional marker: this format's target `handler` isn't wired yet,
+     * so it temporarily routes through the legacy agent-extraction path and is
+     * excluded from `assetUploadExtensions()` (preserving today's behavior).
+     * Remove it when the real handler lands — docx when the deterministic
+     * markdown convert ships (P2); svg when `sanitize-html` is wired (P3) — at
+     * which point the format flows to `uploadAsset` like every other asset.
+     */
+    transitional?: 'agent-extract';
+}
+/**
+ * The disposition for any file the registry doesn't recognize: a generic
+ * opaque asset, never content-indexed. `resolveFormat` returns this exact
+ * (frozen) reference for unknown types so callers can identity-check it —
+ * the P0 dispatcher rejects on `entry === FALLBACK_ASSET_ENTRY` to preserve
+ * today's reject behavior; P0b removes that guard to accept unknowns
+ * leniently (the only behavior change between the two phases).
+ */
+export declare const FALLBACK_ASSET_ENTRY: FormatEntry;
+/** Look up a format by extension (dot-prefixed or bare). */
+export declare function lookupByExtension(ext: string): FormatEntry | undefined;
+/** Look up a format by MIME type. */
+export declare function lookupByMime(mime: string): FormatEntry | undefined;
+/**
+ * Resolve the disposition for a file. Never returns undefined — unknown
+ * types resolve to `FALLBACK_ASSET_ENTRY` (identity-checkable). Extension is
+ * the primary key; `mime` is a fallback when the filename carries no usable
+ * extension. Bookmark detection is by content (`isNetscapeBookmarkFile`),
+ * NOT handled here.
+ */
+export declare function resolveFormat(filename: string, mime?: string): FormatEntry;
+/** A format is searchable when it declares any index extraction. */
+export declare function isIndexable(entry: FormatEntry): boolean;
+/**
+ * Extensions whose bytes are stored as a binary asset (category `asset` or
+ * `asset-convertible`), plus `.csv` — which is a direct-dataset on the web
+ * import path but has historically been accepted by `uploadAsset` too (the
+ * agent `import_file` tool stores a dropped `.csv` as an opaque asset). Kept
+ * in the set so `isAssetUploadExtension` preserves that behavior exactly.
+ * Returned WITHOUT the leading dot to match the legacy `base.ts` set.
+ */
+export declare function assetUploadExtensions(): Set<string>;
+/**
+ * Extensions the `import-service` text path participates in — verbatim
+ * direct-write formats, anything with a text/caption extractor, and the
+ * sanitized SVG. Used to derive `import-service`'s `isSupportedFile`.
+ *
+ * This is a (small) superset of the legacy literal — it additionally
+ * includes `.xlsx`, `.avif`, `.heic` — but every one of those extra
+ * extensions is an asset-upload extension, so it is caught by
+ * `isAssetUploadExtension` *before* `isSupportedFile` is ever consulted in
+ * the only live caller (the agent `import_file` tool). The observable
+ * behavior is therefore identical to the legacy set. Dot-prefixed.
+ */
+export declare function importServiceExtensions(): Set<string>;
+/**
+ * Per-ingress capability (P4, Codex drift-guard). Each ingress path has a
+ * different trust model, so "which formats may travel this path" is a property
+ * of the format + the path, expressed here in the registry rather than as a
+ * special-case in the presign/upload code:
+ *
+ *  - `presign`   — MCP pre-signed PUT straight to R2. The app NEVER holds the
+ *    bytes, so it cannot sanitize them. Only formats that are safe as raw bytes
+ *    are eligible: image assets with no `sanitize` requirement and font assets.
+ *    This is what keeps SVG (sanitize: 'svg') and every doc/video/opaque type
+ *    OFF the presign path without a hardcoded list.
+ *  - `inline`    — MCP base64 bytes through the app (V3) OR web multipart. The
+ *    app holds the bytes, so it CAN sanitize — SVG is allowed here (sanitize
+ *    runs before store). Any asset the upload pipeline accepts is inline-able.
+ *  - `multipart` — alias of `inline` for the web upload route's perspective.
+ *
+ * A format is presign-safe iff: it's an image asset or font asset, needs no
+ * sanitization, and isn't transitional. Images cover png/jpeg/gif/webp/avif/heic;
+ * fonts cover woff2/woff/ttf/otf.
+ */
+export declare function isPresignSafe(entry: FormatEntry): boolean;
+/** A format may travel the inline/multipart path iff the upload pipeline takes
+ *  it (any asset, including ones that need sanitizing — the app holds the bytes
+ *  and sanitizes before store). Excludes still-transitional formats. */
+export declare function isInlineUploadAllowed(entry: FormatEntry): boolean;
+/**
+ * MIME allowlist for the MCP PRESIGN path (Content-Type gate baked into the PUT
+ * signature). Derived from `isPresignSafe` — NOT every asset MIME. The presign
+ * service + the MCP tool's mime enum both read this so they can't drift.
+ */
+export declare function presignMimeAllowlist(): string[];
+/**
+ * MIME allowlist for the INLINE-bytes / multipart path (V3 — the app holds the
+ * bytes and can sanitize). Broader than presign: includes SVG and the
+ * convertible docs. Drives the V3 `upload_asset_inline` MCP tool's gate.
+ */
+export declare function inlineUploadMimeAllowlist(): string[];
+/**
+ * The HTML `accept` attribute value covering every ingestible format
+ * (extensions + MIME types). The single source the client's fragmented
+ * accept lists collapse onto (P5).
+ */
+export declare function acceptAttribute(): string;
+/**
+ * JSON-safe projection of the registry for `GET /api/formats`. The client
+ * builds its accept lists, disposition matrix, and supported-types copy from
+ * this — `supported-file-types.ts` becomes a derived view (P5).
+ */
+export declare function serializeForClient(): {
+    formats: FormatEntry[];
+    accept: string;
+};
+/** All registered entries (read-only view). */
+export declare function allFormats(): FormatEntry[];