@lesliechan721/aw-plugin-core 0.1.0-beta.3 → 0.1.0-beta.31

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { PluginManifestSourceV1 } from './generated/plugin-manifest-v1.js';
+import type { PluginManifestSourceV3 } from './generated/plugin-manifest-v3.js';
 export type PlatformName = 'codex' | 'claude';
 export type DistributionName = 'agent-skills';
 export type Scope = 'project' | 'user';
@@ -10,7 +10,7 @@ export type CatalogSourceId = string;
 export type SourceIdentity = string;
 export type SupportedPlatformSet = ReadonlySet<PlatformName>;
 export type CodexProjectManagedKind = 'skill' | 'mcpServer' | 'instruction' | 'permission' | 'hook' | 'agent';
-export type PluginInterfaceMeta = NonNullable<PluginManifestSourceV1['interface']>;
+export type PluginInterfaceMeta = NonNullable<PluginManifestSourceV3['interface']>;
 export interface MarketplaceOwner {
     name: string;
     url: string;
@@ -25,9 +25,9 @@ export interface MarketplaceSourceMeta {
         version: string;
     };
 }
-export type MarketplacePolicy = PluginManifestSourceV1['marketplace']['policy'];
+export type MarketplacePolicy = PluginManifestSourceV3['marketplace']['policy'];
 export type MarketplaceAuthenticationPolicy = MarketplacePolicy['authentication'];
-export type PluginMarketplaceMeta = PluginManifestSourceV1['marketplace'];
+export type PluginMarketplaceMeta = PluginManifestSourceV3['marketplace'];
 export type TemplateValue = string | boolean;
 export interface TemplateVarByPlatform {
     claude: TemplateValue;
@@ -55,6 +55,11 @@ export interface BuildConfigManifestOverrides {
 export interface BuildConfigRuntimeExport {
     name: string;
     source: string;
+    requires: {
+        aw: {
+            capabilities: string[];
+        };
+    };
 }
 export interface BuildConfigImportReference {
     plugin: string;
@@ -86,18 +91,10 @@ export interface BuildConfig {
     skillRuntimeFiles?: BuildConfigSkillRuntimeFile[];
     generatedSkillRuntimeFiles?: BuildConfigGeneratedSkillRuntimeFile[];
 }
-export type PluginLifecycleEvent = 'install' | 'upgrade' | 'uninstall';
-export type PluginLifecycleOsSelector = 'default' | 'unix' | 'windows' | 'linux' | 'darwin' | 'win32';
-export type PluginLifecycleRuntimeOs = 'linux' | 'darwin' | 'win32';
-export type PluginLifecycleScriptRunner = 'node' | 'sh' | 'bash' | 'pwsh' | 'powershell' | 'cmd' | 'auto';
-export interface PluginLifecycleScriptEntry {
-    runner: PluginLifecycleScriptRunner;
+export interface PluginPreApplyScript {
     path: string;
-    args?: string[];
+    timeoutMs?: number;
 }
-export type PluginLifecycleScriptSelector = Partial<Record<PluginLifecycleOsSelector, PluginLifecycleScriptEntry>>;
-export type PluginLifecycleScriptDefinition = string | PluginLifecycleScriptSelector;
-export type PluginLifecycleScripts = Partial<Record<PluginLifecycleEvent, PluginLifecycleScriptSelector>>;
 export interface PluginScriptHelpersConfig {
     config: string;
 }
@@ -122,26 +119,99 @@ export interface PluginArtifactScriptsConfig {
     render?: PluginArtifactRenderScriptEntry;
 }
 export interface PluginScriptsConfig {
-    timeoutMs?: number;
-    lifecycle?: PluginLifecycleScripts;
+    preApply?: PluginPreApplyScript;
     helpers?: PluginScriptHelpersConfig;
     node?: PluginNodeScriptsConfig;
     artifacts?: PluginArtifactScriptsConfig;
     tests?: PluginScriptTestsConfig;
 }
-export type PluginConfigFieldType = 'string' | 'number' | 'boolean' | 'enum' | 'file' | 'directory';
-export interface PluginConfigSchemaField {
-    type: PluginConfigFieldType;
+export type PluginConfigScalar = string | number | boolean;
+export type PluginConfigObject = Record<string, PluginConfigScalar>;
+export type PluginConfigValue = PluginConfigScalar | PluginConfigObject;
+export type PluginConfigFieldType = 'string' | 'number' | 'boolean' | 'object';
+export type PluginConfigStringFormat = 'identifier' | 'slug' | 'semver' | 'url' | 'hostname' | 'email';
+export interface PluginConfigPreset<Value extends PluginConfigValue = PluginConfigValue> {
+    id: string;
+    title: string;
+    description?: string;
+    value: Value;
+    recommended?: true;
+}
+export interface PluginConfigChoices<Value extends PluginConfigValue = PluginConfigValue> {
+    allowCustom: boolean;
+    presets: PluginConfigPreset<Value>[];
+}
+export interface PluginConfigStringValidation {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: PluginConfigStringFormat;
+}
+export interface PluginConfigNumberValidation {
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+}
+export interface PluginConfigObjectValidation {
+    minProperties?: number;
+    maxProperties?: number;
+    key?: PluginConfigStringValidation;
+}
+export interface PluginConfigFieldBase<Value extends PluginConfigValue> {
     title?: string;
     description?: string;
-    default?: string | number | boolean;
+    default?: Value;
     required?: boolean;
-    sensitive?: boolean;
-    values?: string[];
-    min?: number;
-    max?: number;
+    sensitive?: never;
+}
+interface PluginConfigPlainStringField extends Omit<PluginConfigFieldBase<string>, 'sensitive'> {
+    type: 'string';
+    sensitive?: false;
+    choices?: PluginConfigChoices<string>;
+    validation?: PluginConfigStringValidation;
+}
+interface PluginConfigSensitiveStringField extends Omit<PluginConfigFieldBase<string>, 'default' | 'sensitive'> {
+    type: 'string';
+    sensitive: true;
+    default?: never;
+    choices?: never;
+    validation?: PluginConfigStringValidation;
+}
+export type PluginConfigStringField = PluginConfigPlainStringField | PluginConfigSensitiveStringField;
+export interface PluginConfigNumberField extends PluginConfigFieldBase<number> {
+    type: 'number';
+    choices?: PluginConfigChoices<number>;
+    validation?: PluginConfigNumberValidation;
+}
+export interface PluginConfigBooleanField extends PluginConfigFieldBase<boolean> {
+    type: 'boolean';
+    choices?: PluginConfigChoices<boolean>;
+}
+export type PluginConfigScalarField = PluginConfigStringField | PluginConfigNumberField | PluginConfigBooleanField;
+type DistributiveOmit<Value, Key extends PropertyKey> = Value extends unknown ? Omit<Value, Key> : never;
+type PluginConfigNonSensitiveScalarField = PluginConfigPlainStringField | PluginConfigNumberField | PluginConfigBooleanField;
+export type PluginConfigObjectPropertyField = DistributiveOmit<PluginConfigNonSensitiveScalarField, 'default' | 'sensitive'> & {
+    sensitive?: never;
+};
+export type PluginConfigAdditionalPropertiesField = DistributiveOmit<PluginConfigNonSensitiveScalarField, 'default' | 'required' | 'sensitive'> & {
+    sensitive?: never;
+};
+interface PluginConfigObjectFieldBase extends PluginConfigFieldBase<PluginConfigObject> {
+    type: 'object';
+    choices?: PluginConfigChoices<PluginConfigObject>;
+    validation?: PluginConfigObjectValidation;
+}
+export interface PluginConfigFixedObjectField extends PluginConfigObjectFieldBase {
+    properties: Record<string, PluginConfigObjectPropertyField>;
+    additionalProperties?: false;
 }
-export type PluginConfigPresentationValue = string | number | boolean;
+export interface PluginConfigKeyValueObjectField extends PluginConfigObjectFieldBase {
+    properties?: never;
+    additionalProperties: PluginConfigAdditionalPropertiesField;
+}
+export type PluginConfigObjectField = PluginConfigFixedObjectField | PluginConfigKeyValueObjectField;
+export type PluginConfigSchemaField = PluginConfigScalarField | PluginConfigObjectField;
 export interface PluginConfigPresentationGroup {
     id: string;
     title: string;
@@ -149,28 +219,23 @@ export interface PluginConfigPresentationGroup {
     fields: string[];
     advanced?: boolean;
 }
-export interface PluginConfigPresentationField {
-    valueLabels?: Record<string, string>;
-    recommendedValue?: PluginConfigPresentationValue;
-    placeholder?: string;
-    unit?: string;
-    advanced?: boolean;
-}
-export interface PluginConfigPresentationPreset {
-    id: string;
-    title: string;
-    description?: string;
-    values: Record<string, PluginConfigPresentationValue>;
-}
 export interface PluginConfigPresentation {
     groups?: PluginConfigPresentationGroup[];
-    fields?: Record<string, PluginConfigPresentationField>;
-    presets?: PluginConfigPresentationPreset[];
 }
-export interface PluginConfigSchema {
-    schema: Record<string, PluginConfigSchemaField>;
+export interface PluginConfigDefinition {
+    fields: Record<string, PluginConfigSchemaField>;
     presentation?: PluginConfigPresentation;
 }
+export type PluginConfigSchema = PluginConfigDefinition;
+export interface PluginConfigValidationIssue {
+    code: string;
+    path: {
+        field: string;
+        property?: string;
+    };
+    message: string;
+    recoverable: true;
+}
 export interface PlatformAgentOverrides<T> {
     claude?: Partial<T> | null;
     codex?: Partial<T> | null;
@@ -239,6 +304,15 @@ export interface PluginExtensions {
     agents?: AgentDefinition[];
 }
 export type ArtifactState = 'present' | 'disabled';
+export interface CodexNativeSkillDelivery {
+    mode: 'codex-native';
+    identity: 'shared';
+    renderProfile: 'user';
+}
+export interface AwExtensionSkillDelivery {
+    mode: 'aw-extension';
+}
+export type CodexSkillDelivery = CodexNativeSkillDelivery | AwExtensionSkillDelivery;
 export type ArtifactTarget = 'codex.developerInstructionsBlock' | 'codex.agentRole' | 'codex.skill' | 'claude.skill' | 'agent-skills.skill';
 export type DynamicArtifactKind = 'instruction' | 'codexRole' | 'skill';
 export type ManagedArtifactId = string;
@@ -250,14 +324,15 @@ export interface ArtifactRuntimeImportDefinition extends BuildConfigImportRefere
         providerPluginId: PluginId;
         providerVersion: PluginVersion;
         source: string;
+        requiredCapabilities: string[];
+        capabilitySetDigest: string;
     };
 }
-export interface PluginArtifactTargetDefinition {
+interface PluginArtifactTargetDefinitionBase {
     id: string;
     platform?: PlatformName;
     distribution?: DistributionName;
     scopes: Scope[];
-    target: ArtifactTarget;
     kind?: DynamicArtifactKind;
     projectManagedKind?: CodexProjectManagedKind;
     states: ArtifactState[];
@@ -268,6 +343,13 @@ export interface PluginArtifactTargetDefinition {
     sourceDirs?: string[];
     runtimeImports?: ArtifactRuntimeImportDefinition[];
 }
+export type PluginArtifactTargetDefinition = PluginArtifactTargetDefinitionBase & {
+    target: 'codex.skill';
+    delivery: CodexSkillDelivery;
+} | PluginArtifactTargetDefinitionBase & {
+    target: Exclude<ArtifactTarget, 'codex.skill'>;
+    delivery?: never;
+};
 export interface PluginArtifactsConfig {
     targets?: PluginArtifactTargetDefinition[];
 }
@@ -277,15 +359,14 @@ export interface PluginAgentSkillsDistribution {
 export interface PluginDistributionsConfig {
     agentSkills?: PluginAgentSkillsDistribution;
 }
-export interface PluginCompatibility {
+export interface PluginRequirements {
     aw: {
-        minVersion: CliVersion;
+        capabilities?: string[];
     };
 }
-export type PluginManifestSource = PluginManifestSourceV1;
-export type NormalizedPluginManifest = Omit<PluginManifestSourceV1, 'schemaVersion' | 'compatibility' | 'extensions' | 'artifacts' | 'buildConfig' | 'scripts' | 'config'> & {
-    schemaVersion: 1;
-    compatibility: PluginCompatibility;
+export type PluginManifestSource = PluginManifestSourceV3;
+export type NormalizedPluginManifest = Omit<PluginManifestSourceV3, 'requires' | 'extensions' | 'artifacts' | 'buildConfig' | 'scripts' | 'config'> & {
+    requires?: PluginRequirements;
     extensions?: PluginExtensions;
     artifacts?: PluginArtifactsConfig;
     buildConfig?: BuildConfig;
@@ -295,6 +376,7 @@ export type NormalizedPluginManifest = Omit<PluginManifestSourceV1, 'schemaVersi
 export interface PluginMeta {
     sourceId?: CatalogSourceId;
     sourceIdentity?: SourceIdentity;
+    catalogLogicalIdentity?: string;
     pluginId?: PluginId;
     marketplaceName?: string;
     rootDir: string;
@@ -326,12 +408,13 @@ export interface CatalogManifestEntry {
     tags?: string[];
     strict: boolean;
     policy: MarketplacePolicy;
-    compatibility: PluginCompatibility;
+    dependencies: PluginId[];
+    requires: PluginRequirements;
     source: string;
     artifactDigest: string;
     manifestDigest: string;
 }
-export interface CatalogManifestV4Entry extends CatalogManifestEntry {
+export interface CatalogManifestV7Entry extends CatalogManifestEntry {
     name: PluginId;
     contentDigest: string;
 }
@@ -339,29 +422,25 @@ export interface CatalogMarketplaceIdentity {
     owner: MarketplaceOwner;
     interface: MarketplaceInterfaceMeta;
 }
-export type CatalogManifestV4Release = {
+export type CatalogManifestV7Release = {
     state: 'development';
 } | {
     state: 'published';
-    targetVersion: string;
-    planId: string;
     sourceHead: string;
-    contentDigest: string;
 };
-export interface CatalogManifestV4 {
-    schemaVersion: 4;
+export interface CatalogManifestV7 {
+    schemaVersion: 7;
     catalogVersion: string;
     channel: CatalogChannel;
-    compatibility: PluginCompatibility;
+    requires: PluginRequirements;
     marketplace: CatalogMarketplaceIdentity;
-    release: CatalogManifestV4Release;
-    entries: CatalogManifestV4Entry[];
+    release: CatalogManifestV7Release;
+    entries: CatalogManifestV7Entry[];
 }
 export interface PlatformPluginManifest {
     name: string;
     version: PluginVersion;
     description: string;
-    compatibility: PluginCompatibility;
     skills?: string;
     mcpServers?: string;
     apps?: string;
@@ -426,3 +505,4 @@ export interface ClaudeSkillArtifact extends ArtifactPlanArtifactBase {
         files?: Record<string, string>;
     };
 }
+export {};

package/dist/workspace.d.ts

@@ -1,14 +1,13 @@
-import { type PluginReleaseLedger } from './plugin-release.js';
 import type { ReservedImportRegistry } from './manifest-contract.js';
-import type { CatalogChannel, CatalogManifestV4, MarketplaceSourceMeta, PluginMeta } from './types.js';
-export declare const DEFAULT_WORKSPACE_CATALOG_VERSION = "0.1.0";
+import type { CatalogChannel, CatalogManifestV7, CatalogManifestV7Entry, MarketplaceSourceMeta, PluginMeta } from './types.js';
+export declare const DEFAULT_CATALOG_WORKSPACE_VERSION = "0.1.0";
 export declare const DEFAULT_CATALOG_OUTPUT_PATH: string;
 export declare const DEFAULT_PUBLISHED_CATALOG_OUTPUT_PATH: string;
 export declare const DEFAULT_PLUGIN_OUTPUT_PATH: string;
 export declare const CATALOG_MANIFEST_FILENAME = "catalog-manifest.json";
 export declare const GENERATED_OUTPUT_MARKER_FILENAME = ".aw-generated.json";
-export declare const WORKSPACE_MARKER_FILENAME = ".aw-workspace.json";
-export interface WorkspaceCatalogInitOptions {
+export declare const CATALOG_WORKSPACE_MARKER_FILENAME = ".aw-workspace.json";
+export interface CatalogWorkspaceInitOptions {
     workspaceRoot: string;
     ownerName?: string;
     ownerUrl?: string;
@@ -16,7 +15,7 @@ export interface WorkspaceCatalogInitOptions {
     catalogVersion?: string;
     force?: boolean;
 }
-export interface WorkspacePluginBuildAdapter {
+export interface CatalogWorkspacePluginBuildAdapter {
     build(options: {
         workspaceRoot: string;
         plugin: PluginMeta;
@@ -25,11 +24,24 @@ export interface WorkspacePluginBuildAdapter {
         outputRoot: string;
     }): Promise<void>;
 }
-export type WorkspaceCatalogBuildAdapter = WorkspacePluginBuildAdapter;
-export interface WorkspaceSourceOptions {
+export type CatalogWorkspaceBuildAdapter = CatalogWorkspacePluginBuildAdapter;
+export interface CatalogWorkspaceSourceOptions {
     reservedImports?: ReservedImportRegistry;
 }
-export declare function resolveWorkspaceOutputPath(options: {
+export type CatalogVersionBump = 'major' | 'minor' | 'patch';
+export interface CatalogVersionMutation {
+    version?: string;
+    bump?: CatalogVersionBump;
+}
+export interface CatalogWorkspace {
+    workspaceRoot: string;
+    markerPath: string;
+    workspaceIdentity: string;
+    metadataPath: string;
+    metadata: MarketplaceSourceMeta;
+    plugins: PluginMeta[];
+}
+export declare function resolveCatalogWorkspaceOutputPath(options: {
     workspaceRoot: string;
     outputPath: string;
     kind?: 'catalog' | 'plugin';
@@ -37,24 +49,27 @@ export declare function resolveWorkspaceOutputPath(options: {
     workspaceRoot: string;
     outputRoot: string;
 }>;
-export declare function initializePluginWorkspace(options: WorkspaceCatalogInitOptions): Promise<{
-    workspaceRoot: string;
-    metadataPath: string;
-    metadata: MarketplaceSourceMeta;
+export declare function readCatalogWorkspaceMarker(workspaceRoot: string): Promise<{
+    markerPath: string;
+    workspaceIdentity: string;
 }>;
-export declare function readPluginWorkspace(workspaceRoot: string, options?: WorkspaceSourceOptions): Promise<{
+export declare function initializeCatalogWorkspace(options: CatalogWorkspaceInitOptions): Promise<{
     workspaceRoot: string;
+    markerPath: string;
+    workspaceIdentity: string;
     metadataPath: string;
     metadata: MarketplaceSourceMeta;
-    plugins: PluginMeta[];
 }>;
-export declare function setWorkspaceCatalogVersion(workspaceRoot: string, version: string, options?: WorkspaceSourceOptions): Promise<MarketplaceSourceMeta>;
+export declare function readCatalogWorkspace(workspaceRoot: string, options?: CatalogWorkspaceSourceOptions): Promise<CatalogWorkspace>;
+export declare function resolveCatalogVersionMutation(currentVersion: string, mutation: CatalogVersionMutation): string;
+export declare function mutateCatalogWorkspaceVersion(workspaceRoot: string, mutation: CatalogVersionMutation, options?: CatalogWorkspaceSourceOptions): Promise<MarketplaceSourceMeta>;
 export declare function deriveCatalogChannel(version: string): CatalogChannel;
-export declare function buildWorkspaceCatalog(options: {
+export declare function calculateCatalogWorkspaceSourceIdentity(workspace: Pick<CatalogWorkspace, 'workspaceRoot' | 'metadataPath' | 'plugins'>): Promise<string>;
+export declare function buildCatalogWorkspace(options: {
     workspaceRoot: string;
     outputPath?: string;
     force?: boolean;
-    adapter: WorkspaceCatalogBuildAdapter;
+    adapter: CatalogWorkspaceBuildAdapter;
     reservedImports?: ReservedImportRegistry;
 }): Promise<{
     outputRoot: string;
@@ -64,16 +79,16 @@ export declare function buildWorkspaceCatalog(options: {
 }>;
 export declare function validatePublishedCatalogSnapshot(snapshotDirectory: string): Promise<{
     rootDir: string;
-    manifest: CatalogManifestV4;
-    ledger: PluginReleaseLedger;
+    manifest: CatalogManifestV7;
     snapshotDigest: string;
 }>;
-export declare function preparePublishedWorkspaceCatalog(options: {
+export declare function preparePublishedCatalogWorkspace(options: {
     workspaceRoot: string;
     sourceHead: string;
     outputPath?: string;
     previousSnapshotRoot?: string;
-    adapter: WorkspaceCatalogBuildAdapter;
+    historicalPluginEntries?: readonly CatalogManifestV7Entry[];
+    adapter: CatalogWorkspaceBuildAdapter;
     reservedImports?: ReservedImportRegistry;
 }): Promise<{
     outputRoot: string;
@@ -81,15 +96,13 @@ export declare function preparePublishedWorkspaceCatalog(options: {
     channel: CatalogChannel;
     pluginNames: string[];
     snapshotDigest: string;
-    contentDigest: string;
-    planId: string;
 }>;
-export declare function buildWorkspacePlugin(options: {
+export declare function buildCatalogWorkspacePlugin(options: {
     workspaceRoot: string;
     pluginDirectory: string;
     outputPath?: string;
     force?: boolean;
-    adapter: WorkspacePluginBuildAdapter;
+    adapter: CatalogWorkspacePluginBuildAdapter;
     reservedImports?: ReservedImportRegistry;
 }): Promise<{
     outputRoot: string;
@@ -97,9 +110,21 @@ export declare function buildWorkspacePlugin(options: {
     dependencies: string[];
     digest: string;
 }>;
-export declare function validateCatalogSnapshot(snapshotDirectory: string): Promise<{
+export declare function validatePublishedCatalogSnapshotMetadata(snapshotDirectory: string): Promise<{
     rootDir: string;
-    manifest: CatalogManifestV4;
-    ledger?: PluginReleaseLedger;
+    workspaceIdentity: string;
+    manifest: CatalogManifestV7;
+}>;
+export declare function validateCatalogSnapshotTransport(snapshotDirectory: string): Promise<{
+    rootDir: string;
+    manifest: CatalogManifestV7;
     snapshotDigest: string;
 }>;
+type CatalogSnapshotValidationResult = {
+    rootDir: string;
+    manifest: CatalogManifestV7;
+    snapshotDigest: string;
+};
+export declare function validateCatalogSnapshotPluginEntriesComplete(snapshotDirectory: string, pluginNames: readonly string[]): Promise<CatalogSnapshotValidationResult>;
+export declare function validateCatalogSnapshotComplete(snapshotDirectory: string): Promise<CatalogSnapshotValidationResult>;
+export {};