@deepseek-ai/dsh-settings 0.1.6-alpha.2 → 0.1.7-alpha.2

package/lib/types/index.d.ts

@@ -1,123 +1,33 @@
-/**
- * Service Definition for the user-settings capability seam (`ctx.settings`). Providers store one raw document of
- * per-namespace sections; plugins register a namespace schema and read the
- * resolved value, which layers schema defaults, the registrant's composition
- * `base`, and the user document section, in that order.
- * @module @deepseek-ai/dsh-settings
- */
-import { Context, Service } from '@deepseek-ai/cordis';
-import type z from '@deepseek-ai/schemastery';
-import type { RedactedSecret } from './redact.ts';
-import type { SettingsNamespace, SettingsUpdateSource } from './types.ts';
+import { Context, Service, type Fiber } from '@deepseek-ai/cordis';
+import { type RedactedSecret } from './redact.ts';
+import type { SettingsNamespace } from './types.ts';
 export { redactSecrets } from './redact.ts';
 export type { RedactedSecret, RedactedValue } from './redact.ts';
-export type { SettingsNamespace, SettingsUpdateSource } from './types.ts';
-type LowercaseLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
-type DecimalDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-type NamespaceCharacter = LowercaseLetter | DecimalDigit | '-';
-type ValidNamespaceTail<Value extends string> = Value extends '' ? true : Value extends `${NamespaceCharacter}${infer Rest}` ? ValidNamespaceTail<Rest> : false;
-type SettingsNamespaceInput<Value extends string> = Value extends SettingsNamespace ? Value : string extends Value ? string : Value extends `${LowercaseLetter}${infer Rest}` ? ValidNamespaceTail<Rest> extends true ? Value : never : never;
-/** When a namespace's changes take effect for its owner. */
-export type SettingsApplies = 'live' | 'restart';
-/** Registration options beyond the namespace schema. */
-export interface SettingsRegisterOptions<T> {
-    /** Composition-layer values resolved below the user layer (entry-config subset). */
-    base?: Partial<T>;
-    /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
-    applies?: SettingsApplies;
-    /**
-     * Reject a resolved section the owner could not act on, for constraints its
-     * schema cannot express — a cross-field requirement, or one field's validity
-     * depending on another's. Throwing here refuses the *write* that produced the
-     * value, so a caller learns at `update`/`replace`/`mutate` instead of storing
-     * something that would silently disable the owner.
-     *
-     * Kept separate from the schema because the schema is also what a
-     * configuration surface renders and what an absent section resolves through;
-     * folding a cross-field check into it would change both.
-     *
-     * Once the owner is registered, a stored section that fails this keeps the
-     * namespace's last good value and warns, exactly as a schema failure does,
-     * so an externally edited document cannot strand a running owner. At
-     * registration there is no last good value yet, so a stored section that
-     * already fails rejects the registration itself — again exactly as a schema
-     * failure does.
-     * @param value - the resolved section, schema-valid by construction.
-     */
-    validate?: (value: T) => void;
-}
-/** One registered namespace as surfaced to configuration UIs. */
+export type { SettingsNamespace } from './types.ts';
+/** One Loader entry's live Config fields. */
 export interface SettingsDescriptor {
-    /** The registered namespace. */
     ns: SettingsNamespace;
-    /** Serialized schemastery schema (`schema.toJSON()`). */
+    /** Whether the UI may generate a page when no custom page exists. */
+    autoGenerate: boolean;
     schema: unknown;
-    /** Current resolved value. */
     value: unknown;
-    /**
-     * Monotonic revision of the raw user section this descriptor was read at.
-     * Send it back as `expectedRevision` on a write to refuse a stale one.
-     */
     revision: number;
-    /** Registrant's composition `base` layer (detached), when one was declared. */
     base?: unknown;
-    /**
-     * Raw user section from the stored document (detached), when one exists and
-     * is well-formed; a field's presence here is what marks it user-overridden.
-     */
     user?: unknown;
-    /** Owner's declared effect timing. */
-    applies: SettingsApplies;
-    /** Schema-declared secret positions; present only under `redactSecrets`. */
+    applies: 'live';
     secrets?: RedactedSecret[];
 }
-/** Options for {@link SettingsProvider.describe}. */
+/** Wire readers always request secret redaction. */
 export interface SettingsDescribeOptions {
-    /**
-     * Strip `role('secret')` fields from `value`/`base`/`user` and enumerate
-     * them in each descriptor's `secrets`. Every wire surface MUST pass this;
-     * the verbatim default exists for same-process configuration UIs only.
-     */
     redactSecrets?: boolean;
 }
-/** Owner-facing handle for one registered namespace. */
-export interface SettingsScope<T> {
-    /** Current resolved value: schema defaults, then `base`, then the user layer. */
-    get(): T;
-    /**
-     * Observe committed changes to this namespace's resolved value. Invocations
-     * of one callback run asynchronously, one at a time, in commit order; a
-     * rejection is contained and logged like a sync throw. After the disposer
-     * returns, no further invocation starts — one already queued is skipped;
-     * one already started still settles, and service disposal waits for it.
-     * @param callback - invoked after each commit with the next and previous values.
-     * @returns the disposer removing this observer.
-     */
-    watch(callback: (next: T, prev: T) => void | Promise<void>): () => void;
-    /**
-     * Merge a partial patch into this namespace's user layer and persist it.
-     * @param patch - plain-object patch over the user section; JSON-compatible data
-     * only (non-JSON values reject with their path before anything persists).
-     */
-    update(patch: object): Promise<void>;
-    /**
-     * Replace this namespace's user section wholesale; absent keys re-inherit
-     * the composition `base` and schema defaults (`replace({})` resets all).
-     * @param section - the complete next user section; JSON-compatible data only,
-     * as for {@link update}.
-     */
-    replace(section: object): Promise<void>;
-}
 declare module '@deepseek-ai/cordis' {
     interface Context {
-        settings: SettingsProvider;
+        /** Schema-derived plugin configuration forms. */
+        settings: SettingsForms;
     }
 }
-/**
- * A write refused because the namespace moved since the caller read it. The
- * Service Definition's serialized write queue orders writes; it cannot tell a fresh writer
- * from one holding a stale snapshot, which is what this reports.
- */
+/** Refusal to overwrite configuration changed since the form was read. */
 export declare class SettingsConflictError extends Error {
     /** Stable machine code for wire layers mapping this to their own taxonomy. */
     readonly code = "SETTINGS_CONFLICT";
@@ -148,189 +58,62 @@ export type SettingsPathOp = {
     op: 'unset';
     path: readonly string[];
 };
-/**
- * Abstract settings service. Providers implement raw-document storage
- * (`load`/`persist`) and push external changes through {@link Settings.publish};
- * the base class owns namespace registration, resolution, validation, change
- * detection, and the `settings/updated` commit event.
- */
-export declare abstract class SettingsProvider extends Service {
-    private readonly registrations;
-    /** Latest published raw document; empty until the provider's first publish. */
-    private document;
-    /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */
-    private readonly writeQueues;
-    /** In-flight watcher invocation segments, drained by the dispose teardown. */
-    private readonly pendingTails;
-    /** Set at service dispose: refuse new writes while queued ones drain. */
-    private stopped;
-    /** Opaque read of {@link stopped}: control flow cannot narrow it across awaits. */
-    private isStopped;
-    constructor(ctx: Context);
-    /**
-     * Load the provider's document once and publish it before the service
-     * becomes injectable, and register the write-drain teardown. Providers with
-     * their own init (watchers, connections) delegate here first via
-     * `yield* super[Service.init]()`; their disposers then run before the drain.
-     */
-    [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void>;
-    /** Whether {@link update} may persist through this provider. */
-    abstract readonly writable: boolean;
-    /**
-     * Absolute path of the provider's user-editable document, when its storage
-     * is one local file. Configuration surfaces use this only as availability
-     * metadata; the guarded open operation resolves the path again Host-side.
-     * Non-file providers leave it undefined and expose no open-document affordance.
-     * @returns the absolute local document path, or undefined for non-file storage.
-     */
-    get documentPath(): string | undefined;
-    /**
-     * Prepare the provider's user-editable document for a native editor. File
-     * providers may materialize an absent document before returning its path;
-     * non-file providers return undefined.
-     * @returns the absolute local document path, or undefined for non-file storage.
-     */
-    prepareDocument(): Promise<string | undefined>;
-    /**
-     * Read the provider's current raw document (namespace to raw section).
-     * @returns the detached raw document.
-     */
-    protected abstract load(): Promise<Record<string, unknown>>;
-    /**
-     * Durably store one namespace's merged user section.
-     * @param ns - the namespace being written.
-     * @param section - the complete merged user section to store.
-     */
-    protected abstract persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void>;
-    /**
-     * Register a namespace schema and receive its owner scope. The registration
-     * is an effect on the calling plugin's fiber: disposing that fiber removes
-     * the namespace and its observers. An invalid stored section fails the
-     * registration itself — the earliest point where the schema can judge it.
-     * @param ns - unique namespace; duplicate registration fails loud.
-     * @param schema - schemastery schema resolving this namespace's value.
-     * @param options - composition `base` layer and effect timing.
-     * @returns the owner scope for reads, observation, and updates.
-     * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
-     */
-    register<const Namespace extends string, T>(ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>;
-    /**
-     * Attach one optional-settings consumer to this provider. The consumer
-     * registers its composition entry as the base layer while this provider is
-     * present, then falls back to that entry if the provider detaches.
-     * @param owner - consumer context whose unload suppresses fallback work.
-     * @param ns - consumer-owned settings namespace.
-     * @param schema - schema resolving the namespace.
-     * @param entry - composition entry used as the base and fallback value.
-     * @param hooks - source sink, change notification, and optional validation.
-     * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
-     */
-    installSection<const Namespace extends string, T>(owner: Context, ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>): void;
-    /**
-     * Describe every registered namespace for configuration surfaces, including
-     * the composition `base` and raw user layers so a form can mark which fields
-     * the user overrode (presence in `user`) and what a reset returns to.
-     * @param options - redaction switch; wire surfaces must redact.
-     * @returns one descriptor per registered namespace, in registration order.
+/** Project Config schemas into forms and own optional instance-level UI policy. */
+export declare class SettingsForms extends Service {
+    private readonly ownerContext;
+    static inject: string[];
+    private revisions;
+    private closed;
+    private scheduled;
+    private readonly presentations;
+    constructor(ownerContext: Context);
+    /** Move the sections of the removed `settings.yaml` into the active profile once the Loader has settled every entry.
+     * The document is renamed before the first write, so a partial import never repeats; a section the running
+     * composition rejects is logged and remains only in the renamed file. */
+    private importLegacyDocument;
+    /** Register the calling plugin instance's page policy without changing its Config.
+     * @param presentation Automatic-page policy for this instance; `auto` defaults to true.
+     * @param owner Plugin instance the policy belongs to; defaults to the calling fiber.
+     * @returns Disposer; register it with the calling plugin's effects.
+     * @throws If this instance already has a registered policy.
+     */
+    configure(presentation: {
+        auto?: boolean;
+    }, owner?: Fiber): () => void;
+    private invalidate;
+    /** Whether the active profile accepts form edits. */
+    get writable(): boolean;
+    /** Current profile patch shown by the native configuration editor. */
+    get documentPath(): string;
+    /** Locate the profile patch for native editing.
+     * @returns The existing profile patch path.
+     */
+    prepareDocument(): Promise<string>;
+    /** Read active plugin schemas and their live values.
+     * @param options Redaction required for remote callers.
+     * @returns Forms keyed by unique profile entry ids.
      */
     describe(options?: SettingsDescribeOptions): SettingsDescriptor[];
-    /**
-     * Read one registered namespace's resolved value.
-     * @param ns - the namespace to read.
-     * @returns the resolved value, or `undefined` while unregistered.
-     * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
-     */
-    get<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>): unknown;
-    /**
-     * Merge a patch into one registered namespace's user layer, validate the
-     * resolved candidate, persist through the provider, then commit and emit.
-     * A validation failure rejects before anything is persisted. Writes to one
-     * namespace are serialized: concurrent updates apply in call order, each
-     * merging over the previous write's committed section.
-     * @param ns - the registered namespace to update.
-     * @param patch - plain-object patch over the user section.
-     * @param expectedRevision - the descriptor `revision` the caller read; a
-     *   namespace that moved past it rejects with {@link SettingsConflictError}.
-     * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
-     */
-    update<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>, patch: object, expectedRevision?: number): Promise<void>;
-    /**
-     * Replace one registered namespace's user section wholesale, validate,
-     * persist, then commit and emit. Keys absent from `section` fall back to the
-     * composition `base` and schema defaults — this is the removal/reset path a
-     * merge-only patch cannot express (`replace({})` re-inherits everything).
-     * @param ns - the registered namespace to replace.
-     * @param section - the complete next user section.
-     * @param expectedRevision - the descriptor `revision` the caller read; a
-     *   namespace that moved past it rejects with {@link SettingsConflictError}.
-     * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
-     */
-    replace<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>, section: object, expectedRevision?: number): Promise<void>;
-    /**
-     * Apply path-addressed edits to one registered namespace's user section,
-     * validate, persist, then commit and emit. The ops are applied to the
-     * section as it stands when the write reaches the front of the queue, so a
-     * caller never has to restate fields it did not touch — and, crucially,
-     * cannot delete fields it never saw. This is the write path for any caller
-     * holding a redacted view; `replace` remains the wholesale reset.
-     * @param ns - the registered namespace to edit.
-     * @param ops - ordered path edits; later ops observe earlier ones.
-     * @param expectedRevision - the descriptor `revision` the caller read; a
-     *   namespace that moved past it rejects with {@link SettingsConflictError}.
-     * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
-     */
-    mutate<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>;
-    /** Validate a write, then queue it on the namespace's serialized write chain. */
+    /** Merge editable fields into an entry's config.
+     * @param ns Profile entry id.
+     * @param patch Fields to merge.
+     * @param expectedRevision Revision returned by describe.
+     */
+    update(ns: string, patch: object, expectedRevision?: number): Promise<void>;
+    /** Reset all live fields, then set the supplied fields; ordinary config is preserved.
+     * @param ns Profile entry id.
+     * @param section Complete form values.
+     * @param expectedRevision Revision returned by describe.
+     */
+    replace(ns: string, section: object, expectedRevision?: number): Promise<void>;
+    /** Apply field edits without restating redacted secrets; unsetting an array index removes its element.
+     * @param ns Profile entry id.
+     * @param ops Ordered form edits.
+     * @param expectedRevision Revision returned by describe.
+     */
+    mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>;
     private write;
-    /**
-     * Provider hook: commit a complete raw document observed in storage. Each
-     * registered namespace re-resolves; an invalid section keeps that
-     * namespace's last good value and warns, other namespaces still commit.
-     * @param doc - the detached raw document (unregistered sections preserved).
-     * @param source - change origin; defaults to `provider`.
-     */
-    protected publish(doc: Record<string, unknown>, source?: SettingsUpdateSource): void;
-    /** Read one namespace's raw user section, rejecting non-object sections. */
-    private section;
-    /** Resolve one namespace value: schema defaults, then `base`, then the user layer. */
-    private resolve;
-    /**
-     * Advance a namespace's revision when its RAW section changed, and announce
-     * it. Deliberately independent of {@link commit}'s resolved-value equality:
-     * storing an override equal to the composition base leaves the resolved
-     * value alone but changes what the document says, which is exactly what a
-     * configuration surface must re-read.
-     */
-    private bumpRevision;
-    /** Contained fan-out of `settings/document-updated`, mirroring {@link commit}'s. */
-    private emitDocumentUpdated;
-    /** Commit a resolved value when changed: swap, notify watchers, emit the event. */
-    private commit;
-    /** Contained-watcher diagnostic shared by the sync and async failure paths. */
-    private warnWatcherFailure;
-    /** Contained-listener diagnostic shared by the sync and async failure paths. */
-    private warnListenerFailure;
-}
-/** Hooks a consumer hands to {@link SettingsProvider.installSection}. */
-export interface SettingsSectionHooks<T> {
-    /**
-     * Receive the active configuration source: the resolved settings scope
-     * while one is attached, the composition entry otherwise. Called before
-     * the matching `onChange` at attach and at detach.
-     * @param current - thunk returning the currently authoritative value.
-     */
-    setSource(current: () => T): void;
-    /**
-     * Re-judge anything derived from the source — registration-level facts,
-     * memoized resolutions — after an attach, a detach, or a committed change.
-     */
-    onChange(): void;
-    /**
-     * Reject a resolved section this consumer could not act on, for constraints
-     * its schema cannot express. See {@link SettingsRegisterOptions.validate}.
-     * @param value - the resolved section, schema-valid by construction.
-     */
-    validate?: (value: T) => void;
+    private schema;
 }
-export default SettingsProvider;
+export default SettingsForms;
 //# sourceMappingURL=index.d.ts.map