@dsh-enhanced/assistant-policy 0.1.65 → 0.1.67

package/lib/plugin-setup.d.ts

@@ -0,0 +1,167 @@
+import { type EffectiveProfileDumpReader } from './profile-setup.js';
+export interface PluginSetupTarget {
+    dshHome: string;
+    /** Omit to use `DSH_PROFILE` or the only profile under `$DSH_HOME/profiles`. */
+    profile?: string;
+}
+export interface PluginSetupOptions {
+    /** Test seam; defaults to the approved Host `--dump-config`. */
+    readDump?: EffectiveProfileDumpReader;
+    /** Compute and report the change without writing. */
+    dryRun?: boolean;
+}
+export interface ProfilePluginSummary {
+    id: string;
+    slug: string;
+    packageName: string;
+    /** Loader row gate (`disabled: true` means the plugin is not loaded). */
+    loaded: boolean;
+    /** Top-level `enabled` config gate when the plugin has one. */
+    enabled?: boolean;
+    /** Feature flags: top-level `*Enabled` booleans and one-level `<key>.enabled`. */
+    flags: Record<string, boolean>;
+    /** True when the profile patch already overrides this row. */
+    overridden: boolean;
+}
+export interface PluginChange {
+    id: string;
+    key: string;
+    from: unknown;
+    to: unknown;
+}
+export interface PluginSkip {
+    id: string;
+    reason: string;
+}
+export interface PluginWriteResult {
+    profile: string;
+    patchPath: string;
+    changed: boolean;
+    dryRun: boolean;
+    changes: PluginChange[];
+    skipped: PluginSkip[];
+}
+export declare function resolvePluginProfile(target: PluginSetupTarget): Promise<string>;
+/** Secret-bearing key names; handles/env names/paths/ttls are not secrets. */
+export declare function isSecretConfigKey(name: string): boolean;
+/** Map `work-items`, `assistant-work-items`, `@dsh-enhanced/assistant-work-items` or the row id to an installed row id. */
+export declare function resolvePluginId(name: string, installed: Iterable<string>): string | undefined;
+/**
+ * Convert a CLI string to the type of the current effective value. Unknown keys
+ * need `force`; documented optional keys are typed from a small table.
+ */
+export declare function coerceConfigValue(id: string, key: string, raw: string, current: unknown, force?: boolean): unknown;
+export declare function listProfilePlugins(target: PluginSetupTarget, options?: PluginSetupOptions): Promise<{
+    profile: string;
+    patchPath: string;
+    plugins: ProfilePluginSummary[];
+}>;
+/** Effective config of one plugin with secret-like values redacted. */
+export declare function showProfilePlugin(target: PluginSetupTarget & {
+    plugin: string;
+}, options?: PluginSetupOptions): Promise<{
+    profile: string;
+    summary: ProfilePluginSummary;
+    config: string;
+}>;
+/**
+ * Enable or disable one plugin: flips the loader row gate and, when the plugin
+ * has a top-level `enabled` config gate, that gate too.
+ */
+export declare function setPluginEnabled(target: PluginSetupTarget & {
+    plugin: string;
+    enabled: boolean;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/** Set one config key (dotted path) after validating it against the effective value type. */
+export declare function setPluginConfigValue(target: PluginSetupTarget & {
+    plugin: string;
+    key: string;
+    value: string;
+    force?: boolean;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/** Remove one config key from the profile override so the plugin default applies. */
+export declare function unsetPluginConfigValue(target: PluginSetupTarget & {
+    plugin: string;
+    key: string;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/**
+ * A setting that must already be configured by an owner-facing setup before this
+ * preset may turn on the feature that depends on it. The preset never invents
+ * model routes, evaluation rules, signed pins or signing keys.
+ */
+export interface PresetRequirement {
+    /** Installed plugin (row id, package name or short slug) that owns the setting. */
+    plugin: string;
+    /** Dotted config path that must already be present in the effective profile. */
+    key: string;
+    /** Exact value the existing setting must have. Absent means presence only. */
+    equals?: boolean | string;
+    /** The existing value must be a non-empty array. */
+    nonEmptyArray?: boolean;
+    /** Extra structural check on the existing value. */
+    validate?: (value: unknown) => boolean;
+    /** Shown as the skip reason when this requirement is not met. */
+    reason: string;
+}
+export interface PresetItem {
+    id: string;
+    purpose: string;
+    set: ReadonlyArray<readonly [key: string, value: boolean | string]>;
+    /** Only applied when every requirement is already configured; never generated here. */
+    requires?: readonly PresetRequirement[];
+    /** Reported as skipped with this reason instead of guessing an ambiguous value. */
+    manual?: string;
+}
+/**
+ * The `recommended` preset deliberately turns on opt-in features that stay off
+ * by default. It edits only plugins that are installed and loaded, never loads
+ * a disabled plugin, never touches credentials, Policy, owner routes or sealed
+ * plugin state, and leaves the automations scheduler to the RSI/supervised setup.
+ *
+ * Settings whose authorization is owner-generated (model route and rules for the
+ * intake evaluator, signed background-engineering pins, revision adoption keys)
+ * are never guessed: an item either waits for the explicit configuration and is
+ * skipped with the concrete reason, or is permanently reported as manual.
+ */
+export declare const recommendedPluginPreset: readonly PresetItem[];
+export declare const pluginPresets: ReadonlyMap<string, readonly PresetItem[]>;
+/**
+ * Apply a named plugin preset (default `recommended`) to one profile in a
+ * single verified write. Intended for onboarding flows:
+ *
+ * ```ts
+ * import { applyRecommendedPluginPreset } from '@dsh-enhanced/assistant-policy/plugin-setup'
+ * const result = await applyRecommendedPluginPreset({ dshHome, profile: 'web' })
+ * ```
+ *
+ * Items whose prerequisites are missing are skipped with a concrete reason
+ * instead of being guessed; a manual item is reported as skipped on every run.
+ * Idempotent: re-running reports no changes.
+ */
+export declare function applyPluginPreset(target: PluginSetupTarget & {
+    preset?: string;
+}, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+/** Onboarding entry point: apply the `recommended` plugin preset. */
+export declare function applyRecommendedPluginPreset(target: PluginSetupTarget, options?: PluginSetupOptions): Promise<PluginWriteResult>;
+export type PluginSetupCommand = 'list' | 'show' | 'enable' | 'disable' | 'set' | 'unset' | 'preset' | 'guided';
+export interface PluginSetupArgs {
+    command: PluginSetupCommand;
+    positionals: string[];
+    dshHome: string;
+    profile?: string;
+    force: boolean;
+    dryRun: boolean;
+    yes: boolean;
+    json: boolean;
+    help: boolean;
+}
+export declare function parsePluginSetupArgs(argv: readonly string[]): PluginSetupArgs;
+export declare function pluginSetupUsage(): string;
+export interface PluginSetupIo {
+    write(text: string): void;
+    isTTY: boolean;
+    /** Ask one question; resolves to the trimmed answer. */
+    ask?(question: string): Promise<string>;
+}
+export declare function runPluginSetup(argv?: string[], io?: PluginSetupIo, options?: Omit<PluginSetupOptions, 'dryRun'>): Promise<void>;
+//# sourceMappingURL=plugin-setup.d.ts.map

package/lib/plugin-setup.d.ts.map

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