@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/managers/CatalogManager.d.ts

@@ -0,0 +1,235 @@
+/**
+ * CatalogManager — controlled-vocabulary registry for system keywords (#424).
+ *
+ * Provides a pluggable provider registry so that:
+ *   - Core config-driven terms come from DefaultCatalogProvider
+ *   - Addons contribute domain vocabularies via registerProvider()
+ *   - Future AI-based term suggestion is scaffolded via AICatalogProvider
+ *
+ * Registration pattern (in addon's register() hook):
+ *   const catalog = engine.getManager<CatalogManager>('CatalogManager');
+ *   if (catalog) catalog.registerProvider(new GeoscienceCatalogProvider());
+ *
+ * Related: #424 (CatalogManager), #507 (auto-tagging), #149 (microdata itemid)
+ */
+import BaseManager, { type BackupData, type ManagerStats } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { CatalogProvider, CatalogTerm } from '../types/Catalog.js';
+import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaVersionReport, SchemaType } from '../types/Schema.js';
+export interface UserKeywordConfig {
+    label?: string;
+    description?: string;
+    category?: CatalogTerm['category'];
+    enabled?: boolean;
+    restrictEditing?: boolean;
+    allowedRoles?: string[];
+    uri?: string;
+    source?: string;
+}
+/**
+ * Serves the user-keywords vocabulary (the human tagging bucket in the #869
+ * five-bucket model) through the provider registry, so it shares one interface
+ * with system-keywords: SKOS ConceptScheme emission at
+ * /api/catalog/vocabulary/user-keywords, altLabels aliasing later, and the
+ * drift report's canonical side.
+ *
+ * #896: vocabulary is content, not configuration. Two layers:
+ *   - SEED — `ngdpbase.user-keywords` read from the SHIPPED defaults only
+ *     (`getDefaultProperty`), so legacy whole-catalog snapshots in instance
+ *     custom config can't shadow it (the #895 propagation bug).
+ *   - STORE — `<instance-data>/vocabulary/user-keywords.json`, read-write,
+ *     owned by this provider. Holds instance-created/adopted terms and
+ *     per-key overrides of seed entries (disable = `enabled:false` delta).
+ * `getCatalogObject()` merges the two (store wins per key);
+ * `saveCatalogObject()` diffs against the seed and persists only deltas.
+ * All catalog writes (admin CRUD, drift Adopt, import auto-register) go
+ * through this provider — never through ConfigurationManager.setProperty.
+ */
+export declare class UserKeywordsCatalogProvider implements CatalogProvider {
+    readonly id = "user-keywords";
+    readonly displayName = "User Keywords";
+    readonly domain = "user-keywords";
+    private engine;
+    constructor(engine: WikiEngine);
+    /** Absolute path of the instance vocabulary store. */
+    getStorePath(): string | null;
+    private seedCatalog;
+    private readStore;
+    /**
+     * Full catalog as an id-keyed object (seed merged with store, store wins).
+     * Includes disabled entries — callers filter as needed.
+     */
+    getCatalogObject(): Promise<Record<string, UserKeywordConfig>>;
+    /**
+     * Persist a full catalog object. Only deltas against the seed are written
+     * to the store: entries identical to their seed counterpart are omitted;
+     * seed entries absent from `catalog` are stored as `enabled:false`
+     * overrides (a seed key can't be deleted, only disabled).
+     */
+    saveCatalogObject(catalog: Record<string, UserKeywordConfig>): Promise<void>;
+    /**
+     * #896 backup contract: raw instance-store contents (NOT the merged
+     * catalog — the seed ships with the code and needs no backup).
+     */
+    readStoreForBackup(): Promise<Record<string, UserKeywordConfig>>;
+    /** #896 restore contract: write store contents verbatim (no delta pass). */
+    restoreStore(store: Record<string, UserKeywordConfig>): Promise<void>;
+    getTerms(): Promise<CatalogTerm[]>;
+    resolveUri(term: string): Promise<string | null>;
+}
+declare class CatalogManager extends BaseManager {
+    readonly description = "Two-registry coordinator: vocabulary providers (#424) + asset sources (#755)";
+    private providers;
+    private aiProvider;
+    /**
+     * Asset-source registry (Slice 3 of #755).
+     *
+     * Parallel to the vocabulary `providers` map. Each entry is a Manager
+     * (PageManager, MediaManager, AttachmentManager) that produces CreativeWork
+     * records — see `src/types/Schema.ts` `CatalogSource` interface.
+     */
+    private sources;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Register a catalog provider.
+     * Addons call this in their register() hook to contribute domain vocabularies.
+     * Calling registerProvider() with an id that already exists replaces the prior provider.
+     */
+    registerProvider(provider: CatalogProvider): void;
+    /**
+     * Return all terms from all registered providers, merged in registration order.
+     * @param domain Optional domain filter — only includes providers with a matching domain
+     *               (providers with no domain set are always included).
+     */
+    getTerms(domain?: string): Promise<CatalogTerm[]>;
+    /**
+     * Resolve a term string to a Linked-Data URI.
+     * Walks providers in registration order; returns the first non-null hit.
+     */
+    resolveUri(term: string): Promise<string | null>;
+    /**
+     * Suggest controlled-vocabulary terms for the given page content.
+     * Delegates to any provider that implements suggestTerms().
+     * Returns [] when no AI provider is wired or ai is disabled.
+     */
+    suggestTerms(content: string, title: string): Promise<CatalogTerm[]>;
+    /**
+     * Return info about all registered providers (for admin UIs / diagnostics).
+     */
+    getProviderInfo(): Array<{
+        id: string;
+        displayName: string;
+        domain?: string;
+    }>;
+    /**
+     * Slice 6c of #760 (#767) — return one provider's terms for SKOS emission.
+     * The aggregate `getTerms()` is the wrong surface for SKOS publishing:
+     * `/api/catalog/vocabulary/<scheme-id>` is per-provider, so the route
+     * needs per-provider access. Returns null when the schemeId doesn't match
+     * a registered provider (caller renders 404).
+     */
+    /**
+     * #896: typed accessor for the user-keywords provider — the write interface
+     * for the instance vocabulary store (admin CRUD, drift Adopt, import
+     * auto-register all go through it).
+     */
+    getUserKeywordsProvider(): UserKeywordsCatalogProvider | null;
+    getProviderTerms(schemeId: string): Promise<{
+        displayName: string;
+        terms: CatalogTerm[];
+    } | null>;
+    /**
+     * #1467: canonical keyword value → the vocabulary's display title, for a
+     * caller snapping a page's or an asset's keywords to the catalogued form.
+     *
+     * This map is the vocabulary's own derived view, so it is declared here and
+     * nowhere else. It used to be written out twice — once in `PageManager`
+     * (#915) and once in `WikiRoutes` (#918) — and the `PageManager` copy cast
+     * `getProviderTerms` to an array, which it has never returned. The cast is
+     * what let the mismatch compile; `for...of` then threw on every page save
+     * and the catch swallowed it, so keyword title-snapping never ran at all.
+     *
+     * Best-effort by contract: an empty map when the vocabulary is unreachable,
+     * so a caller's dedup still runs, just without title-snapping.
+     *
+     * Only ENABLED terms are in the map — a disabled term is not part of the
+     * vocabulary, so nothing should be snapped to it.
+     */
+    getCanonicalKeywordMap(schemeId?: string): Promise<Map<string, string>>;
+    /**
+     * Register an asset source (Slice 3 of #755).
+     *
+     * PageManager, MediaManager, AttachmentManager call this during their own
+     * `initialize()` to expose CreativeWork records via this Manager. Replacing
+     * by `sourceId` is allowed (last registration wins).
+     */
+    registerSource(source: CatalogSource): void;
+    /**
+     * Look up a single CreativeWork by stable identifier across all registered
+     * sources. Returns the first non-null hit; returns null when no source has
+     * the identifier or all matching sources filter it out via ACL.
+     *
+     * Pass `opts.sourceId` to restrict the lookup to one source — useful when
+     * the caller already knows which source owns the record.
+     */
+    getCreativeWork(identifier: string, opts?: {
+        sourceId?: string;
+    }): Promise<CreativeWork | null>;
+    /**
+     * List CreativeWorks across registered sources matching the query.
+     *
+     * When `query.types` is set, only sources advertising at least one of the
+     * requested @types are queried. Cursors are scoped to a single source —
+     * callers paginating across multiple sources receive items in source
+     * registration order without a unified cursor (initial slice; can be
+     * extended once a real consumer needs cross-source pagination).
+     */
+    listCreativeWorks(query: CatalogQuery): Promise<CatalogPage>;
+    /**
+     * Check whether each source's on-disk index is up to date with its in-code
+     * `currentSchemaVersion` constant (Decision 6). Sources report `isStale =
+     * true` when the index file lags behind code; the admin dashboard surfaces
+     * a banner per stale source.
+     *
+     * Each source is expected to compare its own on-disk version against
+     * `currentSchemaVersion` and return both numbers. CatalogManager just
+     * aggregates and routes the report to consumers.
+     */
+    checkSchemaVersions(): SchemaVersionReport;
+    /**
+     * Reads the on-disk schemaVersion from a source.
+     *
+     * For now this just returns the source's currentSchemaVersion — the per-file
+     * on-disk schemaVersion machinery (Decision 6) is wired in later slices as
+     * each source's persisted index file gains the `schemaVersion` field.
+     * Until then, all sources report fresh, which matches the actual state
+     * (everything is at v1, no upgrade-from-prior-version path needed yet).
+     */
+    private readOnDiskSchemaVersion;
+    /** Diagnostics — list registered sources for admin UIs / dashboards. */
+    /**
+     * #1006: registered catalog sources, wrapping the existing getSourceInfo().
+     *
+     * This is the shape #780's bespoke source list becomes one row of, which is
+     * the point of the contract: a manager stops needing its own admin page.
+     */
+    getManagerStats(): Promise<ManagerStats>;
+    getSourceInfo(): Array<{
+        sourceId: string;
+        types: readonly SchemaType[];
+        currentSchemaVersion: number;
+    }>;
+    /**
+     * #896: back up the instance vocabulary store(s). Only provider-owned
+     * instance data is included — the seed vocabulary ships with the code and
+     * the AI provider owns no terms. Keyed by provider id so future
+     * provider-owned stores slot in without a format change.
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * #896: restore instance vocabulary store(s) written by backup().
+     */
+    restore(backupData: BackupData): Promise<void>;
+}
+export default CatalogManager;

package/lib/src/managers/CommentManager.d.ts

@@ -0,0 +1,75 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { PageComment } from '../types/Comment.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type VaultPageNotesOutside, type PageRef } from '../utils/pageNotes.js';
+export default class CommentManager extends BaseManager {
+    private commentsDir;
+    private enabled;
+    /** Vault pages whose comments are still in the public folder (#1839), and the repair's re-check (#1842). */
+    private readonly outsideCheck;
+    constructor(engine: WikiEngine);
+    initialize(): Promise<void>;
+    isEnabled(): boolean;
+    /** The public folder and the vaults, as configured now (#1839). */
+    private roots;
+    /**
+     * Where `page`'s comments are (#1839): the public folder for a public page,
+     * the page's own vault for a vault page, read and written through that
+     * vault's store I/O. A locked vault, or a sealed kind's vault not yet
+     * opened, throws: a vault page's comments are never read or written in the
+     * clear.
+     */
+    private place;
+    private commentFile;
+    /**
+     * A page's comments, read as `ctx` may (#1839). Whether `ctx` may read the
+     * page is the caller's to decide, as for the page itself; this finds and
+     * opens them.
+     */
+    getComments(page: PageRef, ctx: ActorContext): Promise<PageComment[]>;
+    /**
+     * Add a comment on someone's behalf (#1232, security-posture P1).
+     *
+     * `ctx` is the request's subject — `wikiContext.userContext`, forwarded —
+     * or a JobContext for an import; never a name. The author and display
+     * name are read from it, and the write is recorded as `comment-create`.
+     */
+    addComment(page: PageRef, ctx: ActorContext, content: string): Promise<PageComment>;
+    /**
+     * Mark a comment deleted on someone's behalf (#1232). Soft: the file stays
+     * with `deleted`, `deletedBy`, `deletedAt`. Recorded as `comment-delete`,
+     * naming whose comment it was and whether the deleter was its author.
+     */
+    deleteComment(page: PageRef, commentId: string, ctx: ActorContext): Promise<boolean>;
+    /** Lazily resolved: AuditManager initialises last, and a missing sink is a configuration state, not a failure. */
+    private auditSink;
+    getComment(page: PageRef, commentId: string, ctx: ActorContext): Promise<PageComment | null>;
+    /**
+     * Take a page's comments with it when it changes place (#1839): into a
+     * vault, out of one, or between two, through both sides' store I/O as its
+     * history goes, sealed into a sealed vault and opened coming out. The page
+     * door calls this after the page itself has moved; a rename in place moves
+     * nothing.
+     */
+    movePageComments(uuid: string, fromName: string, toName: string, ctx: ActorContext): Promise<boolean>;
+    /** Vault pages whose comments the last check found in the public folder (#1839): owner, vault, page uuid. */
+    vaultPageNotesOutside(): VaultPageNotesOutside[];
+    /** Run that check again (#1842): after a repair, so the subsystem banner clears once nothing is left. */
+    recheckVaultPageNotesOutside(): Promise<VaultPageNotesOutside[]>;
+    /**
+     * Move vault page `uuid`'s comments left in the public folder into its
+     * vault (#1842), sealed when the vault is; one the vault already holds is
+     * kept. Who may ask, and that `uuid` is a page of `vault`, is the caller's
+     * (`PageManager.repairVaultPage`) to decide.
+     *
+     * @returns how many comment files were (or, with `dryRun`, would be) moved
+     */
+    moveOutsideCommentsIntoVault(vault: {
+        owner: string;
+        store: string;
+    }, uuid: string, ctx: ActorContext, opts?: {
+        dryRun?: boolean;
+    }): Promise<number>;
+    shutdown(): Promise<void>;
+}