@yugoo-design/dsh-design-studio 0.1.0 → 0.2.0

package/lib/node.d.ts

@@ -0,0 +1,400 @@
+import { D as DesignBundleVersionPin, O as DesignKitVersionPin, a as StudioInstanceFileChange, f as StudioPanelDraftRepository, i as StudioInstanceChangeRequest, l as StudioDraftSources, m as StudioSourceSnapshot, n as StudioInstanceCandidate, r as StudioInstanceChangeReceipt, s as StudioInstanceSaveChanges, v as StudioContentArchive, w as StudioPanelPreviewResult } from "./instance-changes-CFLBPBdi.js";
+//#region src/node/types.d.ts
+type StudioAwaitable<T> = T | Promise<T>;
+interface StudioSourceEntry {
+  readonly path: string;
+  readonly base64: string;
+}
+interface StudioDisplayTitle {
+  readonly zh: string;
+  readonly en: string;
+}
+interface StudioRetainedSource {
+  readonly snapshot: string;
+  readonly sourceId: string;
+}
+interface StudioInstalledKitCapture {
+  readonly name: string;
+  readonly version: string | number;
+  readonly sourceRoot?: string;
+  readonly skills?: readonly {
+    readonly name: string;
+    readonly version: string | number;
+    readonly catalogName?: string;
+    readonly resourceRoot?: string;
+  }[];
+}
+interface StudioNodeStorageOptions {
+  /** Trusted Host adapter; defaults to the cross-platform system trash implementation. */
+  readonly moveToTrash?: (file: string) => Promise<void>;
+  /** Absolute, host-selected state directory; never an installed source root. */
+  readonly stateRoot: string;
+  readonly kitRoot?: string;
+  readonly readInstalledKit?: () => StudioAwaitable<StudioInstalledKitCapture>;
+  readonly readInstalledBundle?: (pin: DesignBundleVersionPin) => StudioAwaitable<{
+    readonly resourceRoot?: string;
+    readonly sourceId?: string;
+  } | undefined>;
+}
+interface StudioInstalledStorageOptions extends StudioNodeStorageOptions {
+  readonly kitRoot: string;
+  readonly readInstalledKit: () => StudioAwaitable<StudioInstalledKitCapture>;
+}
+type StudioNodeDraftSources = StudioDraftSources;
+interface StudioPanelDraftPorts {
+  readonly repository: StudioPanelDraftRepository;
+  readonly sources: StudioNodeDraftSources;
+}
+interface StudioInstanceMount {
+  readonly bindingKey?: string;
+  readonly bundle: DesignBundleVersionPin & {
+    readonly source?: StudioRetainedSource;
+    readonly instanceId?: string;
+    readonly revision?: number;
+  };
+  /** Retained legacy record fields, consumed only by explicit migration. */
+  readonly instanceId?: string;
+  readonly revision?: number;
+}
+interface StudioInstanceStoredRecord {
+  readonly id: string;
+  readonly revision: number;
+  readonly recordVersion?: 1 | 2;
+  readonly kind: 'kit' | 'bundle';
+  readonly title: StudioDisplayTitle;
+  readonly source: {
+    readonly kit?: DesignKitVersionPin;
+    readonly bundle?: DesignBundleVersionPin;
+  };
+  readonly kit?: DesignKitVersionPin;
+  readonly bundle?: DesignBundleVersionPin;
+  readonly runtimeName?: string;
+  readonly sourceId?: string;
+  readonly baseSnapshot: string;
+  readonly overlays: Readonly<Record<string, string>>;
+  readonly mounts: readonly StudioInstanceMount[];
+  readonly current?: boolean;
+  /** Provenance of an unfinished source authoring template; not definition validity. */
+  readonly createdBlank?: boolean;
+  /** Original imported bytes retained by the existing S2 snapshot store. */
+  readonly importedFromSnapshot?: string;
+  readonly createdAt?: string;
+  readonly deletedAt?: string;
+  readonly bundlePath?: string;
+  readonly forkedFrom?: {
+    readonly id: string;
+    readonly revision: number;
+    readonly pin: DesignBundleVersionPin | DesignKitVersionPin;
+  };
+  readonly migration?: {
+    readonly fromRevision: number;
+    readonly fromSnapshot: string;
+  };
+}
+type StudioInstanceContent = Omit<StudioInstanceStoredRecord, 'id' | 'revision'>;
+interface StudioInstanceTransaction {
+  read(id: string): Promise<StudioInstanceStoredRecord>;
+  list(): Promise<readonly StudioInstanceStoredRecord[]>;
+  create(content: StudioInstanceContent): Promise<StudioInstanceStoredRecord>;
+  replace(id: string, expectedRevision: number, content: StudioInstanceContent): Promise<StudioInstanceStoredRecord>;
+  retainTree(entries: readonly StudioSourceEntry[]): Promise<StudioSourceSnapshot>;
+  migrate(id: string, expectedRevision: number, content: StudioInstanceContent): Promise<StudioInstanceStoredRecord>;
+}
+interface StudioInstanceRepository extends Omit<StudioInstanceTransaction, 'retainTree' | 'migrate'> {
+  /** Existing exclusive lock, not a multi-record rollback or publication transaction. */
+  transaction<T>(operation: (transaction: StudioInstanceTransaction) => Promise<T>): Promise<T>;
+}
+interface StudioInstanceDraftPorts {
+  readonly repository: StudioInstanceRepository;
+  readonly sources: StudioNodeDraftSources & {
+    retainTree(entries: readonly StudioSourceEntry[]): Promise<StudioSourceSnapshot>;
+  };
+}
+interface StudioInstanceBundleChoice extends DesignBundleVersionPin {
+  readonly title: StudioDisplayTitle;
+  readonly runtimeName: string;
+  /** Read-only picker copy from the existing Bundle source; never a mount pin. */
+  readonly description?: string;
+  readonly displayDescription?: StudioDisplayTitle;
+  readonly instanceId?: string;
+  readonly revision?: number;
+}
+interface StudioInstanceDescription extends Omit<StudioInstanceStoredRecord, 'overlays' | 'importedFromSnapshot'> {
+  /** Same-identity editable projection of a catalog source. */
+  readonly current?: boolean;
+  readonly refs: readonly {
+    readonly id: string;
+    readonly title: StudioDisplayTitle;
+  }[];
+  readonly readiness?: {
+    readonly ready: boolean;
+    readonly diagnostics: readonly {
+      readonly code: string;
+      readonly message: string;
+      readonly path?: string;
+      readonly severity?: 'error' | 'warning';
+    }[];
+  };
+  readonly requiresMigration?: boolean;
+  readonly description?: string;
+  readonly displayDescription?: StudioDisplayTitle;
+  readonly files?: readonly {
+    readonly path: string;
+    readonly bytes: number;
+    readonly editable: boolean;
+  }[];
+  readonly availableBundles?: readonly StudioInstanceBundleChoice[];
+}
+interface StudioBundleCapture {
+  readonly files: readonly StudioSourceEntry[];
+  readonly sourceId: string;
+}
+type StudioBundleResolver = (pin: DesignBundleVersionPin) => StudioAwaitable<StudioBundleCapture | undefined>;
+interface StudioKitCompositionInput {
+  readonly kit: DesignKitVersionPin;
+  readonly kitFiles: readonly StudioSourceEntry[];
+  readonly mounts: readonly StudioInstanceMount[];
+  readonly resolveBundle: StudioBundleResolver;
+}
+type StudioInstancePreviewInput = ({
+  readonly kind: 'kit';
+} & StudioKitCompositionInput | {
+  readonly kind: 'bundle';
+  readonly bundleFiles: readonly StudioSourceEntry[];
+  readonly runtimeName?: string;
+  readonly sourceId: string;
+}) & {
+  readonly bundle: DesignBundleVersionPin;
+  readonly revision: number;
+  readonly sampleSource?: string;
+};
+interface StudioInstanceCatalog {
+  listBundles(): Promise<readonly StudioInstanceBundleChoice[]>;
+  captureBundle(pin: DesignBundleVersionPin): Promise<StudioBundleCapture & Pick<StudioInstanceBundleChoice, 'title' | 'runtimeName' | 'description' | 'displayDescription'>>;
+  captureKit(pin: DesignKitVersionPin): Promise<{
+    readonly files: readonly StudioSourceEntry[];
+    readonly title?: StudioDisplayTitle;
+    readonly mounts: readonly (DesignBundleVersionPin & {
+      readonly bindingKey: string;
+    })[];
+  }>;
+}
+interface StudioInstanceComposition {
+  loadKit?(input: StudioKitCompositionInput): Promise<import("@yugoo-design/dsh-design-core").DesignKit>;
+  forkBundle(input: {
+    readonly files: readonly StudioSourceEntry[];
+    readonly from: DesignBundleVersionPin;
+    readonly to: DesignBundleVersionPin;
+    readonly runtimeName: string;
+  }): Promise<readonly StudioSourceEntry[]>;
+  /** Draft projection is allowed for Node-owned blank sources and still-incomplete imported Kits. */
+  projectMounts(input: {
+    readonly allowEmptyDraft?: boolean;
+    readonly kit: DesignKitVersionPin;
+    readonly kitFiles: readonly StudioSourceEntry[];
+    readonly mounts: readonly (DesignBundleVersionPin & {
+      readonly bindingKey: string;
+    })[];
+    readonly resolveBundle?: StudioBundleResolver;
+  }): Promise<readonly StudioSourceEntry[]>;
+  /** Partial source import; identity projection does not validate or grant execution. */
+  projectSourceIdentity?(input: {
+    readonly kind: 'kit' | 'bundle';
+    readonly files: readonly StudioSourceEntry[];
+    readonly identity: DesignBundleVersionPin | DesignKitVersionPin;
+  }): StudioAwaitable<readonly StudioSourceEntry[]>;
+  validateBundle?(input: {
+    readonly bundle: DesignBundleVersionPin;
+    readonly bundleFiles: readonly StudioSourceEntry[];
+    readonly sourceId: string;
+    readonly runtimeName: string;
+  }): Promise<void>;
+  validateKit(input: StudioKitCompositionInput): Promise<void>;
+  preview?(input: StudioInstancePreviewInput): Promise<StudioPanelPreviewResult>;
+}
+interface StudioInstanceTrustedCaptures {
+  listBundles(): StudioAwaitable<readonly DesignBundleVersionPin[]>;
+  captureBundle(pin: DesignBundleVersionPin): StudioAwaitable<StudioBundleCapture>;
+  captureKit(pin: DesignKitVersionPin): StudioAwaitable<{
+    readonly files: readonly StudioSourceEntry[];
+    readonly title?: StudioDisplayTitle;
+  }>;
+  preview?(input: StudioInstancePreviewInput): StudioAwaitable<StudioPanelPreviewResult>;
+}
+interface StudioInstanceAdapters {
+  readonly catalog: StudioInstanceCatalog;
+  readonly composition: StudioInstanceComposition;
+}
+interface StudioInstancesOptions extends StudioNodeStorageOptions, StudioInstanceAdapters {}
+interface StudioInstanceArchiveRequest {
+  readonly id: string;
+  readonly expectedRevision: number;
+  readonly provenance?: StudioContentArchive['provenance'];
+  readonly dependencies?: readonly DesignBundleVersionPin[];
+}
+interface StudioInstanceCopyRequest {
+  readonly kind: 'kit' | 'bundle';
+  readonly kit?: DesignKitVersionPin;
+  readonly bundle?: DesignBundleVersionPin;
+  readonly sourceId?: string;
+  readonly expectedRevision?: number;
+  readonly title?: StudioDisplayTitle;
+}
+interface StudioInstanceRevision {
+  readonly id: string;
+  readonly expectedRevision: number;
+}
+interface StudioInstanceReadFile {
+  readonly id: string;
+  readonly revision: number;
+  readonly path: string;
+  readonly content: string;
+}
+interface StudioInstanceImportRequest {
+  readonly kind: 'kit' | 'bundle';
+  readonly files: readonly StudioSourceEntry[];
+  readonly title?: StudioDisplayTitle;
+}
+interface StudioInstances {
+  editCurrent(input: {
+    readonly kind: 'kit' | 'bundle';
+    readonly kit?: DesignKitVersionPin;
+    readonly bundle?: DesignBundleVersionPin;
+  }): Promise<StudioInstanceDescription>;
+  captureKit(input: {
+    readonly id: string;
+    readonly expectedRevision?: number;
+  }): Promise<StudioKitCompositionInput>;
+  loadKit(input: {
+    readonly id: string;
+    readonly expectedRevision?: number;
+  }): Promise<import("@yugoo-design/dsh-design-core").DesignKit>;
+  importSources(input: StudioInstanceImportRequest): Promise<StudioInstanceDescription>;
+  create(input: {
+    readonly kind: 'kit' | 'bundle';
+    readonly title: StudioDisplayTitle;
+  }): Promise<StudioInstanceDescription>;
+  read(input: string | {
+    readonly id: string;
+  }): Promise<StudioInstanceDescription>;
+  list(input?: {
+    readonly kind?: 'kit' | 'bundle';
+  }): Promise<readonly StudioInstanceDescription[]>;
+  listBundles(): Promise<readonly StudioInstanceBundleChoice[]>;
+  copy(input: StudioInstanceCopyRequest): Promise<StudioInstanceDescription>;
+  rename(input: StudioInstanceRevision & {
+    readonly title: StudioDisplayTitle;
+  }): Promise<StudioInstanceDescription>;
+  remove(input: StudioInstanceRevision): Promise<{
+    readonly id: string;
+    readonly revision: number;
+    readonly trashed: true;
+  }>;
+  readFile(input: {
+    readonly id: string;
+    readonly path: string;
+  }): Promise<StudioInstanceReadFile>;
+  saveFile(input: StudioInstanceRevision & {
+    readonly path: string;
+    readonly content: string;
+  }): Promise<StudioInstanceDescription>;
+  exportArchive(input: StudioInstanceArchiveRequest): Promise<string>;
+  prepareChanges(input: StudioInstanceChangeRequest): Promise<StudioInstanceCandidate>;
+  saveChanges(input: StudioInstanceSaveChanges): Promise<StudioInstanceDescription & {
+    readonly changeReceipt: StudioInstanceChangeReceipt;
+  }>;
+  updateMounts(input: StudioInstanceRevision & {
+    readonly bundles: readonly (DesignBundleVersionPin & {
+      readonly bindingKey?: string;
+      readonly instanceId?: string;
+      readonly revision?: number;
+    })[];
+  }): Promise<StudioInstanceDescription>;
+  preview(input: StudioInstanceRevision & {
+    readonly bundle?: DesignBundleVersionPin;
+    readonly sampleSource?: string;
+  }): Promise<StudioPanelPreviewResult>;
+  migrate(input: StudioInstanceRevision): Promise<StudioInstanceDescription>;
+}
+interface StudioAuthoringScope extends StudioInstanceRevision {
+  readonly allowedPaths: readonly string[];
+  readonly bundle?: DesignBundleVersionPin;
+}
+interface StudioAuthoringComponentCatalog {
+  readonly components: readonly {
+    readonly name: string;
+    readonly [key: string]: unknown;
+  }[];
+  readonly [key: string]: unknown;
+}
+interface StudioAuthoringRecord {
+  readonly id: string;
+  readonly revision: number;
+  readonly kind: 'kit' | 'bundle';
+  readonly deletedAt?: string;
+  readonly bundle?: DesignBundleVersionPin;
+  readonly files?: readonly {
+    readonly path: string;
+    readonly bytes: number;
+    readonly editable: boolean;
+  }[];
+  readonly mounts?: readonly {
+    readonly bundle: DesignBundleVersionPin;
+  }[];
+}
+interface StudioAuthoringOptions {
+  readonly scope: StudioAuthoringScope;
+  readonly instances: {
+    read(input: {
+      readonly id: string;
+    }): Promise<StudioAuthoringRecord>;
+    readFile(input: {
+      readonly id: string;
+      readonly path: string;
+    }): Promise<StudioInstanceReadFile>;
+    prepareChanges(input: StudioInstanceChangeRequest): Promise<StudioInstanceCandidate>;
+  };
+  readonly readComponents: () => StudioAwaitable<StudioAuthoringComponentCatalog>;
+}
+type StudioAuthoringReplacement = StudioInstanceFileChange & {
+  readonly content: string;
+};
+interface StudioAuthoring {
+  read(input?: {
+    readonly paths?: readonly string[];
+  }): Promise<{
+    readonly scope: StudioAuthoringScope;
+    readonly files: readonly ({
+      readonly path: string;
+      readonly exists: false;
+    } | {
+      readonly path: string;
+      readonly exists: true;
+      readonly content: string;
+    })[];
+    readonly components: StudioAuthoringComponentCatalog;
+  }>;
+  prepare(input: {
+    readonly changes: readonly StudioAuthoringReplacement[];
+  }): Promise<{
+    readonly scope: StudioAuthoringScope;
+    readonly components: StudioAuthoringComponentCatalog;
+    readonly request: StudioInstanceChangeRequest;
+    readonly candidate: StudioInstanceCandidate;
+  }>;
+}
+//#endregion
+//#region src/node/studio-panel-drafts.d.mts
+declare function createStudioDraftPorts(options: StudioInstalledStorageOptions, kind: 'panel'): Promise<StudioPanelDraftPorts>;
+declare function createStudioDraftPorts(options: StudioNodeStorageOptions, kind: 'instance'): Promise<StudioInstanceDraftPorts>;
+//#endregion
+//#region src/node/studio-instances.d.mts
+declare function createStudioInstances(options: StudioInstancesOptions): Promise<StudioInstances>;
+//#endregion
+//#region src/node/studio-instance-composition.d.mts
+declare function createStudioInstanceAdapters(trusted: StudioInstanceTrustedCaptures): StudioInstanceAdapters;
+//#endregion
+//#region src/node/studio-authoring.d.mts
+declare function createStudioAuthoring(options: StudioAuthoringOptions): StudioAuthoring;
+//#endregion
+export { type StudioAuthoring, type StudioAuthoringComponentCatalog, type StudioAuthoringOptions, type StudioAuthoringRecord, type StudioAuthoringReplacement, type StudioAuthoringScope, type StudioAwaitable, type StudioBundleCapture, type StudioBundleResolver, type StudioDisplayTitle, type StudioInstalledKitCapture, type StudioInstalledStorageOptions, type StudioInstanceAdapters, type StudioInstanceArchiveRequest, type StudioInstanceBundleChoice, type StudioInstanceCatalog, type StudioInstanceComposition, type StudioInstanceContent, type StudioInstanceCopyRequest, type StudioInstanceDescription, type StudioInstanceDraftPorts, type StudioInstanceImportRequest, type StudioInstanceMount, type StudioInstancePreviewInput, type StudioInstanceReadFile, type StudioInstanceRepository, type StudioInstanceRevision, type StudioInstanceStoredRecord, type StudioInstanceTransaction, type StudioInstanceTrustedCaptures, type StudioInstances, type StudioInstancesOptions, type StudioKitCompositionInput, type StudioNodeDraftSources, type StudioNodeStorageOptions, type StudioPanelDraftPorts, type StudioRetainedSource, type StudioSourceEntry, createStudioAuthoring, createStudioDraftPorts, createStudioInstanceAdapters, createStudioInstances };