studiograph 1.3.47 → 1.3.48-beta.1

package/dist/services/notification-service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Polymorphic notification feed. Phase 1 only ever writes `source_type='comment'`
+ * (the messaging-era 'message' source died with the messaging surface in Phase
+ * 0). The polymorphic shape stays so future surfaces can ride the same wire.
+ */
+export interface Notification {
+    id: number;
+    userId: number;
+    sourceType: string;
+    sourceId: string;
+    mentionerUserId: number;
+    mentionerDisplayName: string;
+    preview: string;
+    read: 0 | 1;
+    createdAt: string;
+}
+export interface InsertNotificationInput {
+    userId: number;
+    sourceType: string;
+    sourceId: string;
+    mentionerUserId: number;
+    mentionerDisplayName: string;
+    preview: string;
+}
+export declare class NotificationService {
+    private db;
+    constructor(workspacePath: string);
+    /** Insert a notification and return the new id. */
+    insert(input: InsertNotificationInput): number;
+    list(userId: number, opts?: {
+        limit?: number;
+        unreadOnly?: boolean;
+    }): Notification[];
+    unreadCount(userId: number): number;
+    markRead(notificationId: number, userId: number): boolean;
+    markAllRead(userId: number): number;
+    /** Remove all notifications referencing a given source (used when a comment is hard-deleted). */
+    deleteBySource(sourceType: string, sourceId: string): number;
+    close(): void;
+    private toNotification;
+}

package/dist/services/notification-service.js

@@ -0,0 +1,100 @@
+import Database from 'better-sqlite3';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, chmodSync } from 'node:fs';
+export class NotificationService {
+    db;
+    constructor(workspacePath) {
+        const sgDir = join(workspacePath, '.studiograph');
+        if (!existsSync(sgDir))
+            mkdirSync(sgDir, { recursive: true });
+        const dbPath = join(sgDir, 'notifications.db');
+        this.db = new Database(dbPath);
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch { /* non-fatal */ }
+        }
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS notifications (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id INTEGER NOT NULL,
+        source_type TEXT NOT NULL,
+        source_id TEXT NOT NULL,
+        mentioner_user_id INTEGER NOT NULL,
+        mentioner_display_name TEXT NOT NULL,
+        preview TEXT NOT NULL,
+        read INTEGER NOT NULL DEFAULT 0 CHECK(read IN (0, 1)),
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_notifications_user
+        ON notifications(user_id, read, id DESC)
+    `);
+    }
+    /** Insert a notification and return the new id. */
+    insert(input) {
+        const stmt = this.db.prepare(`
+      INSERT INTO notifications
+        (user_id, source_type, source_id, mentioner_user_id, mentioner_display_name, preview)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(input.userId, input.sourceType, input.sourceId, input.mentionerUserId, input.mentionerDisplayName, input.preview.length > 200 ? input.preview.slice(0, 200) : input.preview);
+        return result.lastInsertRowid;
+    }
+    list(userId, opts = {}) {
+        const limit = Math.min(opts.limit ?? 50, 200);
+        const filter = opts.unreadOnly ? 'AND read = 0' : '';
+        const rows = this.db.prepare(`
+      SELECT id, user_id, source_type, source_id, mentioner_user_id,
+             mentioner_display_name, preview, read, created_at
+      FROM notifications
+      WHERE user_id = ? ${filter}
+      ORDER BY id DESC
+      LIMIT ?
+    `).all(userId, limit);
+        return rows.map(this.toNotification);
+    }
+    unreadCount(userId) {
+        const row = this.db.prepare(`
+      SELECT COUNT(*) AS c FROM notifications WHERE user_id = ? AND read = 0
+    `).get(userId);
+        return row.c;
+    }
+    markRead(notificationId, userId) {
+        const result = this.db.prepare(`
+      UPDATE notifications SET read = 1 WHERE id = ? AND user_id = ?
+    `).run(notificationId, userId);
+        return result.changes > 0;
+    }
+    markAllRead(userId) {
+        const result = this.db.prepare(`
+      UPDATE notifications SET read = 1 WHERE user_id = ? AND read = 0
+    `).run(userId);
+        return result.changes;
+    }
+    /** Remove all notifications referencing a given source (used when a comment is hard-deleted). */
+    deleteBySource(sourceType, sourceId) {
+        const result = this.db.prepare(`
+      DELETE FROM notifications WHERE source_type = ? AND source_id = ?
+    `).run(sourceType, sourceId);
+        return result.changes;
+    }
+    close() {
+        this.db.close();
+    }
+    toNotification = (row) => ({
+        id: row.id,
+        userId: row.user_id,
+        sourceType: row.source_type,
+        sourceId: row.source_id,
+        mentionerUserId: row.mentioner_user_id,
+        mentionerDisplayName: row.mentioner_display_name,
+        preview: row.preview,
+        read: row.read === 1 ? 1 : 0,
+        createdAt: row.created_at,
+    });
+}
+//# sourceMappingURL=notification-service.js.map

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

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

package/dist/services/personal-folder.d.ts

@@ -0,0 +1,40 @@
+import { Workspace } from '../core/workspace.js';
+import type { AuthService, AuthUser } from './auth-service.js';
+/**
+ * Register the user's personal "My Folder" folder and grant them admin
+ * folder_access. Idempotent — safe to call repeatedly and on existing
+ * workspaces where the folder was provisioned before this helper existed
+ * (repairs the missing folder_access row).
+ *
+ * Consolidated from four earlier call sites that each did half the work:
+ * setup endpoint, /api/auth/users POST, server startup sweep, and
+ * `studiograph user add` CLI. Skipping the grant left the user's own
+ * personal folder invisible in the sidebar because `getAccessibleRepos()`
+ * filters by folder_access.
+ */
+export declare function ensurePersonalFolder(workspace: Workspace, authService: AuthService, user: AuthUser): Promise<void>;
+/**
+ * Convert a departed user's personal folder into a normal (non-personal)
+ * archive folder owned by the actor who deleted them. Matches Google
+ * Drive's inherit-on-delete model: the content survives, the owner is
+ * reassigned, and the "personal" semantics fall away so the folder
+ * doesn't clash with the one-personal-folder-per-user invariant.
+ *
+ * Mutations applied (in order, best-effort non-atomic):
+ *  1. Pick a collision-free new name: `archive-{slug}-{YYYY-MM-DD}`,
+ *     escalating to `-2`, `-3`, … if needed.
+ *  2. Rename the folder directory on disk.
+ *  3. Update workspace.json: new name/path, display_name, clear the
+ *     personal/owner_id flags, and write the new `.studiograph` marker.
+ *  4. Update folder_access rows to the new name so the actor's inherited
+ *     admin row keeps working.
+ *  5. Push the updated workspace.json to the config remote (non-fatal).
+ *
+ * Returns the new folder name and display name so the caller can report
+ * them to the UI. The caller should `workspaceManager.reloadConfig()`
+ * after this completes to surface the change to in-memory graph state.
+ */
+export declare function archivePersonalFolder(workspace: Workspace, oldName: string, targetDisplayName: string, authService: AuthService): Promise<{
+    newName: string;
+    newDisplayName: string;
+}>;

package/dist/services/personal-folder.js

@@ -0,0 +1,101 @@
+import { existsSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Register the user's personal "My Folder" folder and grant them admin
+ * folder_access. Idempotent — safe to call repeatedly and on existing
+ * workspaces where the folder was provisioned before this helper existed
+ * (repairs the missing folder_access row).
+ *
+ * Consolidated from four earlier call sites that each did half the work:
+ * setup endpoint, /api/auth/users POST, server startup sweep, and
+ * `studiograph user add` CLI. Skipping the grant left the user's own
+ * personal folder invisible in the sidebar because `getAccessibleRepos()`
+ * filters by folder_access.
+ */
+export async function ensurePersonalFolder(workspace, authService, user) {
+    const folderName = `entries-${user.id}`;
+    const config = await workspace.loadConfig();
+    const alreadyRegistered = config.repos.some(r => r.name === folderName);
+    if (!alreadyRegistered) {
+        await workspace.registerRepo({
+            name: folderName,
+            display_name: 'My Folder',
+            description: `Personal entries for ${user.displayName}`,
+            personal: true,
+            owner_id: user.id,
+        });
+    }
+    const hasAccess = authService.getUserFolders(user.id).includes(folderName);
+    if (!hasAccess) {
+        authService.grantFolderAccess(user.id, folderName, 'admin');
+    }
+}
+/**
+ * Convert a departed user's personal folder into a normal (non-personal)
+ * archive folder owned by the actor who deleted them. Matches Google
+ * Drive's inherit-on-delete model: the content survives, the owner is
+ * reassigned, and the "personal" semantics fall away so the folder
+ * doesn't clash with the one-personal-folder-per-user invariant.
+ *
+ * Mutations applied (in order, best-effort non-atomic):
+ *  1. Pick a collision-free new name: `archive-{slug}-{YYYY-MM-DD}`,
+ *     escalating to `-2`, `-3`, … if needed.
+ *  2. Rename the folder directory on disk.
+ *  3. Update workspace.json: new name/path, display_name, clear the
+ *     personal/owner_id flags, and write the new `.studiograph` marker.
+ *  4. Update folder_access rows to the new name so the actor's inherited
+ *     admin row keeps working.
+ *  5. Push the updated workspace.json to the config remote (non-fatal).
+ *
+ * Returns the new folder name and display name so the caller can report
+ * them to the UI. The caller should `workspaceManager.reloadConfig()`
+ * after this completes to surface the change to in-memory graph state.
+ */
+export async function archivePersonalFolder(workspace, oldName, targetDisplayName, authService) {
+    const config = await workspace.loadConfig();
+    const repo = config.repos.find(r => r.name === oldName);
+    if (!repo) {
+        throw new Error(`Cannot archive '${oldName}' — folder not found in workspace config`);
+    }
+    if (!repo.personal) {
+        throw new Error(`Cannot archive '${oldName}' — not a personal folder`);
+    }
+    const slug = slugify(targetDisplayName);
+    const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const baseName = `archive-${slug}-${date}`;
+    let newName = baseName;
+    let suffix = 2;
+    while (config.repos.some(r => r.name === newName)) {
+        newName = `${baseName}-${suffix}`;
+        suffix += 1;
+    }
+    const wsPath = workspace.workspacePath;
+    const oldPath = join(wsPath, repo.path);
+    const newPath = join(wsPath, newName);
+    if (existsSync(oldPath)) {
+        renameSync(oldPath, newPath);
+    }
+    repo.name = newName;
+    repo.path = newName;
+    repo.display_name = `Archive: ${targetDisplayName} (${date})`;
+    delete repo.personal;
+    delete repo.owner_id;
+    const markerPath = join(newPath, '.studiograph');
+    if (existsSync(markerPath)) {
+        writeFileSync(markerPath, JSON.stringify({ repo_name: newName }, null, 2), 'utf-8');
+    }
+    workspace.writeConfig(config);
+    authService.renameFolder(oldName, newName);
+    workspace.pushWorkspaceConfig(`Archive personal folder on user delete: ${oldName} → ${newName}`);
+    return { newName, newDisplayName: repo.display_name };
+}
+function slugify(name) {
+    const cleaned = name
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '') // strip combining diacritics
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return cleaned || 'user';
+}
+//# sourceMappingURL=personal-folder.js.map

package/dist/services/personal-folder.js.map

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

package/dist/services/user-person-bridge.d.ts

@@ -0,0 +1,118 @@
+/**
+ * User ↔ Person bridge
+ *
+ * Resolves between auth.db user accounts and person entities. The pointer
+ * lives on the person side as `user_handle` (scalar handle, not a wikilink —
+ * users are out-of-graph identities). Workspace-unique: at most one person
+ * entity per auth handle, workspace-wide.
+ *
+ * The lookup primitives here are intentionally cheap (in-memory scan of
+ * already-loaded person entities). No persistent cache in v1 — if profiling
+ * later shows this is hot, add one with explicit invalidation on entity
+ * writes and on createUser/deleteUser.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import { type AuthService, type AuthUser } from './auth-service.js';
+import type { GitUser } from './git.js';
+/** Stable reference to a person entity in the workspace graph. */
+export interface PersonRef {
+    repo: string;
+    entityId: string;
+}
+/** Reason codes returned by `assertUserHandleUnique` / linking flows. */
+export type BridgeErrorCode = 'USER_HANDLE_CONFLICT' | 'USER_HANDLE_UNKNOWN' | 'PERSON_ALREADY_LINKED' | 'PERSON_NOT_FOUND' | 'OWNER_REQUIRED';
+export declare class BridgeError extends Error {
+    readonly code: BridgeErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: BridgeErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Forward lookup: given an auth user handle, return the person entity that
+ * represents them. Returns null when the user has no linked entity (legacy,
+ * unprovisioned, or explicitly unlinked).
+ */
+export declare function findPersonRefForUser(workspace: WorkspaceManager, userHandle: string): PersonRef | null;
+/**
+ * Reverse lookup: given a person-entity target ID (the wikilink target, e.g.
+ * `fritz` from `[[fritz]]`), return the auth user that entity is linked to.
+ * Returns null when the entity isn't linked, doesn't exist, or refers to a
+ * non-existent user (pre-link case).
+ */
+export declare function findUserForPersonRef(workspace: WorkspaceManager, authService: AuthService, targetId: string): AuthUser | null;
+/**
+ * Bulk forward map: handle → personRef for every linked person in the
+ * workspace. Useful for `list_workspace_users` and for migration reporting.
+ */
+export declare function getHandleToPersonRefMap(workspace: WorkspaceManager): ReadonlyMap<string, PersonRef>;
+/**
+ * Workspace-wide uniqueness check. Throws BridgeError(USER_HANDLE_CONFLICT)
+ * when another person entity already carries `userHandle`. The `exceptRef`
+ * lets update paths skip the check for the entity being written.
+ *
+ * Called from the write path (graph-api create/update, agent graph-tools
+ * create/update) before delegating to graph.create/update.
+ */
+export declare function assertUserHandleUnique(workspace: WorkspaceManager, userHandle: string, exceptRef?: PersonRef): void;
+/**
+ * Authz gate: only workspace owners can stamp or change `user_handle` on a
+ * person entity. Mirrors the `ownerOnly()` gate on the dedicated
+ * `link_person_to_user` / `unlink_person_from_user` agent tools — without
+ * this, a non-owner member with folder-write access could rewrite the
+ * bridge via the generic update_entity REST/agent path, "claiming"
+ * another user's auth identity through the agent's Current User prompt.
+ *
+ * Rules:
+ *   - Payload doesn't include `user_handle` → no-op (caller wasn't trying
+ *     to change the bridge).
+ *   - Payload's value equals the current stored value → no-op (a form
+ *     resubmit including the unchanged field shouldn't 403).
+ *   - Caller is a workspace owner → allowed.
+ *   - Anyone else → throw OWNER_REQUIRED.
+ *
+ * Pass `currentHandle = ''` for create paths (no prior entity).
+ */
+export declare function assertCanChangeUserHandle(authUser: AuthUser | null | undefined, currentHandle: string, newHandle: unknown): void;
+/**
+ * Inspect a frontmatter payload for `user_handle` and, if present, validate
+ * uniqueness against the current workspace state. No-op when the field is
+ * absent or empty.
+ *
+ * `exceptRef` is the entity being written (for updates) so the check
+ * doesn't reject an entity for clashing with itself.
+ */
+export declare function validateUserHandleInPayload(workspace: WorkspaceManager, data: Record<string, unknown>, exceptRef?: PersonRef): void;
+/**
+ * Map an AuthUser to a GitUser for commit attribution. Mirrors `reqGitUser`
+ * in graph-api-access.ts — kept here so the registration / CLI sites
+ * (which don't have a Fastify request) can call into the bridge without
+ * importing the request-scoped helper.
+ */
+export declare function authUserToGitUser(user: AuthUser): GitUser;
+/** Result returned by `ensurePersonForUser` so callers can log/UX the action. */
+export type EnsurePersonResult = {
+    action: 'already-linked';
+    ref: PersonRef;
+} | {
+    action: 'linked';
+    ref: PersonRef;
+} | {
+    action: 'created';
+    ref: PersonRef;
+} | {
+    action: 'skipped';
+    reason: string;
+};
+/**
+ * Resolve a person entity for a freshly-registered (or existing) user.
+ *
+ *   1. If the user is already linked, return.
+ *   2. If a person entity carries `email === user.email` and no `user_handle`,
+ *      stamp the handle onto it ("linked" — preserves the user-edited record).
+ *   3. Otherwise auto-create a person entity in the workspace's team repo
+ *      with the user's name/email and the new handle.
+ *
+ * Returns `{ action: 'skipped' }` when no suitable team repo exists and no
+ * email-matchable entity is available — the caller can warn the operator
+ * but should never block user creation on this.
+ */
+export declare function ensurePersonForUser(workspace: WorkspaceManager, authService: AuthService, authUser: AuthUser, gitUser: GitUser): Promise<EnsurePersonResult>;