@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.1

package/lib/types/trash.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Tombstones: paths a caller has removed from their view without destroying the file.
+ *
+ * ## Why a tombstone rather than an unlink
+ *
+ * A view is hardlinks into one authoritative tree, and several callers' views may
+ * hold a link to the same inode. Unlinking the caller's own link would hide the file
+ * from them, but it would also make the removal indistinguishable from a revoked
+ * grant: the next `syncView` compares grants to links, finds a grant with no link,
+ * and puts the link back. Nothing in the filesystem can say "this one was removed on
+ * purpose".
+ *
+ * So removal is recorded rather than performed. A tombstone is a note that says a
+ * path is hidden from one caller's view, checked while the view is being built. The
+ * file keeps its inode, every other caller keeps their link, and restoring is
+ * deleting the note.
+ *
+ * ## What a tombstone is scoped to
+ *
+ * A tombstone belongs to a CALLER, not to a path: two people sharing a document may
+ * disagree about whether it should be in their view. It therefore lives in the
+ * caller's own directory and filters only that caller's view.
+ *
+ * A tombstone is not a permission. It hides what the caller may still be granted;
+ * it never grants anything, and a restore cannot resurrect access that DataOps has
+ * since withdrawn -- the grant is checked first, and a path whose grant is gone
+ * stays gone whatever the tombstone says.
+ *
+ * @module @sparkelf/dsh-knowledge-base/trash
+ */
+/** One removed path, as the trash surface lists it. */
+export interface Tombstone {
+    /** Path relative to the knowledge root, in view coordinates (`<bucket>/<inner>`). */
+    relPath: string;
+    /** Whether the removed entry was a file or a directory. */
+    kind: 'file' | 'directory';
+    /** Display name of whoever removed it. */
+    removedBy: string;
+    /** ISO-8601 instant of removal. */
+    removedAt: string;
+    /**
+     * Where the entry used to sit, when restoring must know more than the path.
+     *
+     * Equal to {@link relPath} for every current tombstone. It is stored rather than
+     * derived because a future version may move a removed document into a holding
+     * area, and a record that only knows where the document is not is not enough to
+     * put it back.
+     */
+    originalPath: string;
+}
+/** What this module found when it opened a caller's trash file. */
+export type TrashRead = {
+    kind: 'absent';
+} | {
+    kind: 'ready';
+    entries: Tombstone[];
+}
+/**
+ * A file exists but could not be read as a trash record.
+ *
+ * Reported rather than swallowed: interpreting it as "empty" would resurrect every
+ * document the caller had removed, and interpreting it as "everything" would hide
+ * their whole tree.
+ */
+ | {
+    kind: 'unreadable';
+    reason: string;
+};
+/**
+ * Absolute path of one caller's trash record.
+ *
+ * @param viewDir - the caller's view directory.
+ * @returns the path of the record, whether or not it exists.
+ */
+export declare function trashPathFor(viewDir: string): string;
+/**
+ * Read a caller's trash record.
+ *
+ * @param viewDir - the caller's view directory.
+ * @returns what the record holds; `absent` for a caller who never removed anything.
+ */
+export declare function readTrash(viewDir: string): Promise<TrashRead>;
+/**
+ * Write a caller's trash record atomically.
+ *
+ * Written to a sibling and renamed into place, because a half-written record would
+ * read as `unreadable` on the next load and hide a caller's whole tree. An empty
+ * entry list removes the file instead of storing `{ entries: [] }`: absence is the
+ * state a caller who removed nothing is already in.
+ *
+ * @param viewDir - the caller's view directory.
+ * @param entries - the complete set of tombstones to keep.
+ */
+export declare function writeTrash(viewDir: string, entries: readonly Tombstone[]): Promise<void>;
+/**
+ * The set of tombstones that hide a path, including those on an ancestor.
+ *
+ * Removing a folder removes what is inside it. Storing a tombstone per descendant
+ * would mean walking the tree on every removal and would leave a document uploaded
+ * into a removed folder afterwards visible in the trash's place; matching ancestors
+ * at read time makes the folder the unit of removal, which is what a caller means
+ * by removing it.
+ *
+ * @param entries - the caller's tombstones.
+ * @param relPath - the path being tested, in view coordinates.
+ * @returns the matching tombstone (itself or an ancestor), or undefined.
+ */
+export declare function tombstoneHides(entries: readonly Tombstone[], relPath: string): Tombstone | undefined;
+/**
+ * Add a tombstone, replacing any it subsumes.
+ *
+ * Removing an already-removed path is not an error -- a double click, or a page that
+ * reloaded mid-request, both produce it -- and the resulting record is the same as
+ * if it had happened once.
+ *
+ * A tombstone on a folder replaces tombstones on its descendants: keeping both would
+ * leave the children hidden after the folder is restored, which is not what restoring
+ * the folder means.
+ *
+ * @param entries - the existing tombstones.
+ * @param added - the tombstone to add.
+ * @returns the new complete list, newest last.
+ */
+export declare function addTombstone(entries: readonly Tombstone[], added: Tombstone): Tombstone[];
+/**
+ * Remove a tombstone, and the ones it subsumed, so the path becomes visible again.
+ *
+ * @param entries - the existing tombstones.
+ * @param relPath - the path being restored.
+ * @returns the remaining tombstones, and whether anything was removed.
+ */
+export declare function removeTombstone(entries: readonly Tombstone[], relPath: string): {
+    entries: Tombstone[];
+    restored: boolean;
+};
+/**
+ * Build the foreign keys a tombstone should never share.
+ *
+ * @param entries - the caller's tombstones.
+ * @returns every hidden path, for a caller that needs a set rather than a predicate.
+ */
+export declare function hiddenPaths(entries: readonly Tombstone[]): Set<string>;

package/lib/types/viewMetadata.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The names of the bookkeeping files this plugin writes into a caller's view.
+ *
+ * A standalone module rather than a constant exported from `views.ts`: the client
+ * needs these names to exclude them from the file tree, and `views.ts` imports
+ * `node:fs/promises`, which the client bundle refuses. Keeping the list here means the
+ * browser bundle stays free of Node builtins while the list still has one home.
+ *
+ * The Host derives its side from this same list -- see `VIEW_METADATA_NAMES` in
+ * `views.ts`, which is checked against the `*PathFor` helpers at module load so a
+ * renamed file cannot silently drop out of the set.
+ *
+ * Only names that live in the VIEW directory belong here. `.kb-pending` is absent on
+ * purpose: it sits under the authoritative root, is never linked into a view, and an
+ * exclusion entry for it could never match anything.
+ *
+ * @module @sparkelf/dsh-knowledge-base/viewMetadata
+ */
+/** File names the explorer must not list, in a stable order. */
+export declare const VIEW_METADATA_FILENAMES: readonly [".kb-audit.jsonl", ".kb-settings.json", ".kb-tree-state.json", ".kb-favorites.json", ".kb-trash.json", ".pinned.json", ".view-mode.json"];