@lesliechan721/aw 0.1.0-beta.10

package/dist/src/tui/controller.d.ts

@@ -0,0 +1,557 @@
+import type { CatalogActivationMode, CatalogSource, CatalogGenerationActiveV1, CatalogGenerationCandidateEvidence, CatalogGenerationSyncResult, CatalogSourceImpact, DependencyScopeOverride, PlatformName, Scope } from '../types.js';
+import type { PortableReview } from '../portable/commands.js';
+import type { CatalogSourceUpdate } from '../utils/catalog-sources.js';
+import type { CatalogGenerationFreshnessState, CatalogGenerationFreshnessResult } from '../utils/catalog-generation-service.js';
+import type { StatusV7Payload, StatusV7PluginSummary, StatusTargetRevision } from '../commands/status-v6.js';
+import type { ReconcileOperationPlan } from '../commands/reconcile-operation-plan.js';
+import type { OfflineCleanupTargetEvidence } from '../commands/offline-cleanup-evidence.js';
+import type { CodexReconcilePlan } from '../utils/codex-reconciler.js';
+import type { OperationPlan } from '../commands/operation-plan.js';
+import type { RebuildProgressFeed, RebuildProgressSnapshot } from '../output/rebuild-progress.js';
+import { type ConfigPageViewModel, type ConfigGroupViewModel, type InstallPlacementDraftViewModel, type PluginListItemViewModel, type PluginDependencyOverviewViewModel, type PortableSkillSelectionViewModel, type SourceHealthViewModel, type SourceDetailViewModel, type TuiViewModel, type UserIssueCategory, type UserIssueViewModel } from './model.js';
+import { type CatalogActivationBlockReason, type ConfigInvalidStoreEvidence, type PluginInstallFilter, type PortableBlockerCode, type TuiPageContext, type TuiRoute, type TuiRouterSnapshot } from './router.js';
+import { type CatalogSourceGenerationViewModel } from './catalog-generation.js';
+import type { CatalogSourceFreshnessViewModel } from './catalog-freshness.js';
+import type { CatalogSessionReusableCandidate } from './catalog-sources/types.js';
+export type PluginWriteOperation = 'install' | 'refreshAndSync' | 'reinstall' | 'uninstall' | 'cleanup' | 'sync';
+export type OperationKind = OperationIntent['kind'];
+export interface IssueOrigin {
+    issueId: string;
+    issueKey: string;
+    category: UserIssueCategory;
+    actionId: string;
+    consumerPluginId?: string;
+    consumerSourceIdentity?: string;
+    consumerPlatform?: PlatformName;
+    consumerScope?: Scope;
+    dependencyPluginId?: string;
+    dependencyPlatform?: PlatformName;
+    dependencyScope?: Scope;
+    dependencyProject?: 'current' | 'other' | null;
+}
+export type OperationIntent = {
+    kind: 'pluginWrite';
+    action: PluginWriteOperation;
+    pluginId: string;
+    platform: PlatformName | 'both';
+    scope: Scope;
+    dependencyScopeOverrides?: DependencyScopeOverride[];
+    dependencyPlacementAdjustment?: true;
+    recoveryDescription?: string;
+    force?: boolean;
+    originIssue?: IssueOrigin;
+} | {
+    kind: 'portableInstall';
+    pluginId: string;
+    scope: Scope;
+    selectedSkills: string[];
+    requestedAgents?: string[];
+} | {
+    kind: 'configSave';
+    pluginId: string;
+    scope: Scope;
+    apply: boolean;
+    retryApply?: true;
+    updates?: Record<string, unknown>;
+    removeKeys?: string[];
+    sensitiveKeys?: string[];
+    privateKeys?: string[];
+    changes?: Array<{
+        key: string;
+        title: string;
+        before: string;
+        after: string;
+        children?: Array<{
+            property: string;
+            before: string;
+            after: string;
+            private?: boolean;
+        }>;
+    }>;
+} | {
+    kind: 'configReset';
+    pluginId: string;
+    scope: Scope;
+    expectedStoreState?: 'invalid';
+    changes?: Array<{
+        key: string;
+        title: string;
+        before: string;
+        after: string;
+        children?: Array<{
+            property: string;
+            before: string;
+            after: string;
+            private?: boolean;
+        }>;
+    }>;
+} | {
+    kind: 'sourceMutation';
+    action: 'add' | 'update' | 'setPrimary' | 'remove';
+    sourceId: string;
+    source?: CatalogSource;
+    update?: CatalogSourceUpdate;
+    changes?: Array<{
+        title: string;
+        before?: string;
+        after?: string;
+        private?: boolean;
+    }>;
+} | {
+    kind: 'catalogGeneration';
+    action: 'activate' | 'update' | 'repair' | 'replaceDamaged' | 'recoverState';
+    sourceId: string;
+    sourceMutation?: {
+        action: 'add';
+        source: CatalogSource;
+    } | {
+        action: 'update';
+        update: CatalogSourceUpdate;
+    };
+    setPrimaryAfterActivation?: boolean;
+} | {
+    kind: 'catalogSourcesRecovery';
+};
+export interface OperationEvidence {
+    catalog: {
+        configDigest: string;
+        compositeDigest: string;
+        generationSetDigest?: string;
+    };
+    source?: {
+        sourceId: string;
+        sourceIdentity: string;
+        requestedRef?: string;
+        resolvedCommit?: string;
+        manifestDigest?: string;
+        snapshotDigest?: string;
+        contentDigest?: string;
+        pluginVersion?: string;
+        catalogVersion?: string;
+        channel?: 'latest' | 'beta';
+    };
+    targetFingerprint?: string;
+    offlineCleanup?: OfflineCleanupTargetEvidence;
+    dependencyPlan?: ReconcileOperationPlan;
+    codexReconcilePlans?: CodexReconcilePlan[];
+    operationPlan?: OperationPlan;
+    preparationWarnings?: string[];
+    codexManager?: {
+        state: 'system' | 'cached' | 'requires-install';
+        packageName: '@openai/codex';
+        version: string;
+    };
+    config?: {
+        scope: Scope;
+        schemaIdentity?: string;
+        storeDigest: string;
+        affectedTargets: Array<{
+            platform: PlatformName;
+            scope: Scope;
+        }>;
+        sharedNativeRenderTargets?: Array<{
+            id: string;
+            skillKey: string;
+            refreshKeys: string[];
+        }>;
+    };
+    resetTarget?: {
+        sourceId: string;
+        pluginName: string;
+        scope: Scope;
+        kind: 'absent' | 'regularFile' | 'symbolicLink' | 'directory';
+        fingerprint: string;
+    };
+    sourceWrite?: {
+        configDigest: string;
+        proposedConfigDigest: string;
+        sourceIdentity?: string;
+        inventoryDigest: string;
+        impactDigest?: string;
+        referenceCount: number;
+        inventoryComplete: boolean;
+        impact?: CatalogSourceImpact;
+    };
+    catalogGeneration?: {
+        action: Extract<OperationIntent, {
+            kind: 'catalogGeneration';
+        }>['action'];
+        previousActive?: CatalogGenerationActiveV1;
+        previousActiveVersion?: string;
+        candidate: CatalogGenerationCandidateEvidence;
+        candidateRelation?: CatalogGenerationFreshnessState;
+        explicitSourceChange?: boolean;
+        exactRepair?: boolean;
+        activationMode?: CatalogActivationMode;
+        impact?: CatalogSourceImpact;
+        impactDigest?: string;
+        impactMode?: 'generation' | 'identityChange';
+        configDigest: string;
+        proposedConfigDigest?: string;
+        proposedSource?: CatalogSource;
+        sourceMutation?: Extract<OperationIntent, {
+            kind: 'catalogGeneration';
+        }>['sourceMutation'];
+        setPrimaryAfterActivation?: boolean;
+    };
+    portable?: PortableReview;
+}
+export interface OperationReviewChange {
+    kind: 'add' | 'change' | 'remove' | 'keep' | 'warning';
+    group?: 'requested' | 'dependencies' | 'projectIntent' | 'userIntent' | 'sharedCodexNative' | 'userActivation' | 'projectActivation' | 'awExtensions' | 'runtime' | 'portableTarget' | 'portableInputs' | 'portableWarnings' | 'configChanges' | 'configImpact' | 'preserved';
+    pluginId?: string;
+    relation?: 'requested' | 'direct' | 'transitive';
+    title: string;
+    description?: string;
+}
+export interface OperationReviewModel {
+    operationId: string;
+    reviewToken: string;
+    expiresAt: number;
+    operationKind: OperationKind;
+    sourceAction?: Extract<OperationIntent, {
+        kind: 'sourceMutation';
+    }>['action'];
+    pluginAction?: PluginWriteOperation;
+    originIssue?: IssueOrigin;
+    title: string;
+    description: string;
+    subject: {
+        name: string;
+        subtitle?: string;
+        sourceLabel?: string;
+        version?: string;
+    };
+    changes: OperationReviewChange[];
+    technicalDetails?: string[];
+    equivalentCommand?: string;
+    primaryLabel: string;
+    destructive?: boolean;
+    requiresConfirmation: boolean;
+    sharedImpact: {
+        pluginIds: string[];
+        warning?: string;
+    };
+    catalogBinding?: {
+        sourceId: string;
+        catalogVersion: string;
+        generationDigestShort: string;
+    };
+}
+export type ReviewPreparationStageId = 'refresh' | 'validate' | 'status' | 'catalog' | 'inventory' | 'dependencyPlan' | 'config' | 'portable' | 'evidence';
+export interface ReviewPreparationStage {
+    id: ReviewPreparationStageId;
+    label: string;
+    state: 'pending' | 'running' | 'completed' | 'failed';
+}
+export interface ReviewPreparationSnapshot {
+    id: string;
+    intent: OperationIntent;
+    state: 'running' | 'failed';
+    stages: ReviewPreparationStage[];
+    currentLabel: string;
+    code?: 'reviewPreparationFailed';
+    message?: string;
+}
+export type OperationExecuteResult = {
+    state: 'succeeded';
+    operationId: string;
+    summary: OperationResultSummary;
+    operationKind: OperationKind;
+    sourceAction?: Extract<OperationIntent, {
+        kind: 'sourceMutation';
+    }>['action'];
+    pluginId?: string;
+    originIssue?: IssueOrigin;
+    returnRoute?: TuiRoute;
+} | {
+    state: 'partial';
+    operationId: string;
+    summary: OperationResultSummary;
+    operationKind: OperationKind;
+    sourceAction?: Extract<OperationIntent, {
+        kind: 'sourceMutation';
+    }>['action'];
+    pluginId?: string;
+    originIssue?: IssueOrigin;
+    returnRoute?: TuiRoute;
+} | {
+    state: 'stale';
+    operationId: string;
+    operationKind: OperationKind;
+    sourceAction?: Extract<OperationIntent, {
+        kind: 'sourceMutation';
+    }>['action'];
+    review: OperationReviewModel;
+    originIssue?: IssueOrigin;
+} | {
+    state: 'blocked';
+    operationId: string;
+    code: string;
+    message: string;
+    operationKind?: OperationKind;
+    sourceAction?: Extract<OperationIntent, {
+        kind: 'sourceMutation';
+    }>['action'];
+    pluginId?: string;
+    returnRoute?: TuiRoute;
+    originIssue?: IssueOrigin;
+    writeMayHaveCompleted?: boolean;
+    verification?: 'issueStillPresent' | 'verificationFailed';
+    summary?: OperationResultSummary;
+};
+export interface OperationResultSummary {
+    code: 'operationSucceeded' | 'operationPartial' | 'operationFailed';
+    message: string;
+    pluginId?: string;
+    action?: PluginWriteOperation;
+    catalogAction?: Extract<OperationIntent, {
+        kind: 'catalogGeneration';
+    }>['action'];
+    catalogGeneration?: Pick<CatalogGenerationSyncResult, 'activeChanged' | 'outcome'> & {
+        catalogVersion: string;
+    };
+    elapsedMs?: number;
+    messages?: string[];
+    configApplied?: boolean;
+    configApplySkippedReason?: 'invalidConfig';
+    configScope?: Scope;
+    configApplyRetryAvailable?: boolean;
+    resetDisposition?: 'absent' | 'deletedFile' | 'unlinkedSymlink' | 'quarantinedDirectory';
+    quarantineBasename?: string;
+    changes?: string[];
+    warnings?: string[];
+    recoveryActions?: string[];
+    planFingerprint?: string;
+    portable?: {
+        selectedSkills: string[];
+        agentMode: 'automatic' | 'explicit';
+        requestedAgents: string[];
+        scope: Scope;
+        materializationDigest: string;
+        skillsCliVersion: string;
+        missing: Array<{
+            skill: string;
+            agent?: string;
+        }>;
+        verificationUnknown: boolean;
+        recovery?: string;
+        failureCode?: string;
+    };
+    targets?: Array<{
+        pluginId?: string;
+        platform: PlatformName;
+        scope: Scope;
+        state: 'completed' | 'kept' | 'failed' | 'skipped';
+        relation?: 'requested' | 'direct' | 'transitive';
+        requiredBy?: string[];
+        errorCode?: 'dependencyStillRequired' | 'codexSystemCliUnsupported' | 'managedCodexAuthorizationRequired' | 'managedCodexUnavailable';
+    }>;
+}
+export interface PluginOperationProgressLine {
+    pluginId: string;
+    platform: PlatformName;
+    scope: Scope;
+    relation: 'requested' | 'direct' | 'transitive';
+    requiredBy: string[];
+    state: 'pending' | 'running' | 'completed' | 'kept' | 'failed' | 'skipped';
+}
+export interface TuiStatusLoadResult {
+    cliChannel?: 'latest' | 'beta';
+    payload: StatusV7Payload;
+    pluginSummaries: StatusV7PluginSummary[];
+    targetRevisions?: StatusTargetRevision[];
+    sourceDetails?: SourceDetailViewModel[];
+    dependencyOverviews?: PluginDependencyOverviewViewModel[];
+    portablePluginIds?: string[];
+    catalogGenerations?: CatalogSourceGenerationViewModel[];
+    sessionGenerationKeys?: Record<string, string>;
+}
+export interface InstallTargetOption {
+    platform: PlatformName;
+    compatible: boolean;
+    disabled?: string;
+}
+export interface SourceReferenceSummaryViewModel {
+    blocked: boolean;
+    inventoryComplete: boolean;
+    installationCount?: number;
+    configCount?: number;
+    lifecycleCount?: number;
+    marketplaceCount?: number;
+    dependencies: Array<{
+        category: 'installation' | 'config' | 'lifecycle' | 'marketplace';
+        pluginId?: string;
+        sourceId?: string;
+        platform?: PlatformName;
+        scope?: Scope;
+    }>;
+}
+export interface TuiControllerDependencies {
+    beginCatalogSession?: (options?: {
+        reuseValidatedGenerations?: boolean;
+    }) => void;
+    loadStatus: (signal: AbortSignal) => Promise<TuiStatusLoadResult>;
+    probeCatalogFreshness?: (sourceId: string, options: {
+        fullValidation: boolean;
+    }, signal: AbortSignal) => Promise<CatalogGenerationFreshnessResult>;
+    inspectSourceRemoval?: (sourceId: string, signal: AbortSignal) => Promise<SourceReferenceSummaryViewModel>;
+    captureEvidence: (intent: OperationIntent, signal?: AbortSignal) => Promise<OperationEvidence>;
+    validateIntent?: (intent: OperationIntent, signal: AbortSignal) => Promise<void>;
+    prepareReviewEvidence?: (intent: OperationIntent, signal: AbortSignal, onStage: (stage: ReviewPreparationStageId) => void | Promise<void>, reusableCandidate?: CatalogSessionReusableCandidate) => Promise<OperationEvidence>;
+    previewDependencyPlacement?: (intent: Extract<OperationIntent, {
+        kind: 'pluginWrite';
+    }>, signal: AbortSignal) => Promise<ReconcileOperationPlan | undefined>;
+    executeIntent: (intent: OperationIntent, expectedEvidence: OperationEvidence, signal?: AbortSignal) => Promise<unknown>;
+    getConfigGroups?: (pluginId: string, layer: {
+        scope: Scope;
+    }, signal: AbortSignal) => Promise<ConfigGroupViewModel[]>;
+    getConfigPage?: (pluginId: string, layer: {
+        scope: Scope | 'effective';
+    }, signal: AbortSignal) => Promise<ConfigPageViewModel>;
+    getConfigResetAvailability?: (pluginId: string, layer: {
+        scope: Scope;
+    }, signal: AbortSignal) => Promise<ConfigResetAvailability>;
+    logError?: (error: unknown, code: string, context?: {
+        privateConfigOperation: boolean;
+    }) => void | Promise<void>;
+    now?: () => number;
+    createToken?: () => string;
+    reviewTtlMs?: number;
+    maxReviewTickets?: number;
+}
+export interface ConfigResetAvailability {
+    exists: boolean;
+    state: 'missing' | 'ready' | 'invalid';
+    targetKind?: 'absent' | 'regularFile' | 'symbolicLink' | 'directory' | 'special';
+    resettable?: boolean;
+    invalidCode?: ConfigInvalidStoreEvidence['code'];
+    sourceIdentityPresent: boolean;
+    sourceIdentity?: string;
+    storeDigest?: string;
+}
+export interface TuiControllerSnapshot {
+    phase: 'idle' | 'loading' | 'ready' | 'error' | 'disposed';
+    cliChannel?: 'latest' | 'beta';
+    router: TuiRouterSnapshot;
+    viewModel?: TuiViewModel;
+    sourceHealth: SourceHealthViewModel[];
+    catalogGenerations: CatalogSourceGenerationViewModel[];
+    catalogFreshness: CatalogSourceFreshnessViewModel[];
+    reloadRequiredSourceIds: string[];
+    progress: RebuildProgressSnapshot;
+    progressTargets: PluginOperationProgressLine[];
+    activeReview?: OperationReviewModel;
+    reviewPreparation?: ReviewPreparationSnapshot;
+    result?: OperationExecuteResult;
+    loadError?: {
+        code: string;
+        message: string;
+    };
+    portableDraft?: PortableSkillSelectionViewModel & {
+        agentMode: 'automatic' | 'explicit';
+        requestedAgents: string[];
+        scope: Scope;
+    };
+    installPlacementDraft?: InstallPlacementDraftViewModel;
+}
+export declare class TuiOperationBlockedError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class TuiConfigInvalidStoreError extends Error {
+    readonly code = "invalidConfigStores";
+    readonly evidence: ConfigInvalidStoreEvidence[];
+    constructor(evidence: ConfigInvalidStoreEvidence[]);
+}
+export declare function operationEvidenceFingerprint(evidence: OperationEvidence): string;
+export declare function operationEvidenceMatches(expected: OperationEvidence, current: OperationEvidence): boolean;
+export declare function userIssueKey(issue: Pick<UserIssueViewModel, 'category' | 'pluginId' | 'dependencyPluginId' | 'dependencyPlatform' | 'dependencyScope' | 'dependencyProject' | 'sourceId' | 'sourceIdentity' | 'platform' | 'scope'>): string;
+export declare function extractPortableError(error: unknown): {
+    code: PortableBlockerCode;
+    diagnosticCode: string;
+};
+export declare class TuiController {
+    #private;
+    readonly dependencies: TuiControllerDependencies;
+    constructor(dependencies: TuiControllerDependencies, progressFeed?: RebuildProgressFeed);
+    get snapshot(): TuiControllerSnapshot;
+    subscribe(listener: (snapshot: TuiControllerSnapshot) => void): () => void;
+    load(): Promise<void>;
+    push(route: TuiRoute, context?: TuiPageContext): void;
+    hasPortableSkills(pluginId: string): boolean;
+    preparePortableInstall(pluginId: string, navigation?: 'push' | 'replace'): Promise<PortableSkillSelectionViewModel>;
+    refreshPortableInstallDraft(pluginId: string): Promise<PortableSkillSelectionViewModel>;
+    togglePortableSkill(name: string): void;
+    selectAllPortableSkills(): void;
+    setPortableAgentMode(mode: 'automatic' | 'explicit', requestedAgents?: string[]): void;
+    setPortableScope(scope: Scope): void;
+    buildPortableInstallReview(): Promise<OperationReviewModel>;
+    startPortableInstallReviewPreparation(): ReviewPreparationSnapshot;
+    discardPortableDraft(): void;
+    replace(route: TuiRoute, context?: TuiPageContext): void;
+    beginConfigFlow(pluginId: string): void;
+    configOrigin(pluginId: string): TuiRoute | undefined;
+    updatePageContext(context: Partial<TuiPageContext>): void;
+    back(): void;
+    discardSourceDraft(owner: string, returnRoute: Extract<TuiRoute, {
+        name: 'sourceList' | 'sourceDetail';
+    }>): void;
+    leaveResult(target?: TuiRoute): void;
+    resetPortableFlowToPreview(pluginId: string, target?: TuiRoute, preserveDraft?: boolean): void;
+    beginInstallFlow(pluginId: string, rootScope: Scope, options?: {
+        adjustingExisting?: boolean;
+    }): void;
+    setInstallRootScope(rootScope: Scope): void;
+    setInstallPlatforms(platforms: PlatformName[]): void;
+    prepareInstallDependencyPlacement(): Promise<boolean>;
+    setDependencyScope(pluginId: string, platform: PlatformName, scope: Scope): Promise<void>;
+    resetDependencyScopes(): Promise<void>;
+    installPlacementIntent(): Extract<OperationIntent, {
+        kind: 'pluginWrite';
+    }>;
+    listPlugins(options: {
+        mode: 'browse' | 'installed';
+        sourceId?: string;
+        query?: string;
+        installFilter?: PluginInstallFilter;
+    }): PluginListItemViewModel[];
+    getPluginOverview(pluginId: string): PluginListItemViewModel | undefined;
+    getPluginDependencyOverview(pluginId: string): PluginDependencyOverviewViewModel | undefined;
+    getBlockingDependents(pluginId: string, platform: PlatformName, scope: Scope): PluginDependencyOverviewViewModel['dependents'];
+    getPlatformPlacement(pluginId: string, platform: PlatformName): PluginListItemViewModel['installedPlacements'][number] | undefined;
+    listInstallTargets(pluginId: string, scope: Scope): InstallTargetOption[];
+    getTargetState(pluginId: string, platform: PlatformName, scope: Scope): StatusV7Payload['targets'][number]['state'] | undefined;
+    listSources(): TuiViewModel['sourceTabs'];
+    getSourceOverview(sourceId: string): {
+        source?: TuiViewModel['sourceTabs'][number];
+        detail?: SourceDetailViewModel;
+        health?: SourceHealthViewModel;
+    };
+    getCatalogGeneration(sourceId: string): CatalogSourceGenerationViewModel | undefined;
+    getCatalogFreshness(sourceId: string): CatalogSourceFreshnessViewModel | undefined;
+    recheckCatalogSource(sourceId: string): Promise<void>;
+    fullValidateCatalogSource(sourceId: string): Promise<void>;
+    setExternalDraftState(state?: 'configDraft' | 'sourceDraft'): void;
+    catalogActivationBlockReason(): CatalogActivationBlockReason | undefined;
+    getSessionCatalogVersion(sourceId: string): string | undefined;
+    reloadCatalog(options: {
+        sourceId: string;
+    }): Promise<boolean>;
+    inspectSourceRemoval(sourceId: string): Promise<SourceReferenceSummaryViewModel>;
+    getConfigGroups(pluginId: string, layer: {
+        scope: Scope;
+    }): Promise<ConfigGroupViewModel[]>;
+    getConfigPage(pluginId: string, layer: {
+        scope: Scope | 'effective';
+    }, signal?: AbortSignal): Promise<ConfigPageViewModel>;
+    getConfigResetAvailability(pluginId: string, layer: {
+        scope: Scope;
+    }): Promise<ConfigResetAvailability>;
+    listUserIssues(): UserIssueViewModel[];
+    buildOperationReview(intent: OperationIntent, returnRoute?: TuiRoute): Promise<OperationReviewModel>;
+    startReviewPreparation(intent: OperationIntent, returnRoute?: TuiRoute): ReviewPreparationSnapshot;
+    retryReviewPreparation(): ReviewPreparationSnapshot | undefined;
+    executeOperation(reviewToken: string): Promise<OperationExecuteResult>;
+    dispose(): void;
+}