@superblocksteam/vite-plugin-file-sync 2.0.74-next.2 → 2.0.75-next.3

package/dist/ai-service/app-interface/shell.d.ts

@@ -1,15 +1,50 @@
 import { type GlobOptionsWithFileTypesUnset } from "glob";
 import { type FileArtifact } from "../types.js";
+import { type DraftChanges, type FileMetadata } from "./filesystem/index.js";
+import type { VirtualFileSystem } from "./filesystem/index.js";
+import type { DraftInterface } from "../../draft-interface.js";
 import type { IOperationQueue } from "../../util/operation-queue.js";
+import type { TemplateRenderer } from "../template-renderer.js";
+/**
+ * Options for listing files with optional metadata.
+ */
+export interface ListFilesOptions extends GlobOptionsWithFileTypesUnset {
+    /** Include file metadata (size, mtime, type). Default: false */
+    includeMetadata?: boolean;
+    /** Include directories in listing. Default: false (files only) */
+    includeDirs?: boolean;
+}
+/**
+ * AppShell provides the primary interface for the AI agent to interact
+ * with the application environment.
+ *
+ * It encapsulates:
+ * - File system operations (read, write, delete, list, rename)
+ * - Virtual file abstraction (APIs appear as single .ts files)
+ * - Draft management for undo/redo capability
+ * - Code quality tools (linting, type checking)
+ * - Package management
+ */
 export declare class AppShell {
     readonly appRootDirPath: string;
     private readonly fsOperationQueue;
     private readonly linter;
     private messageSender?;
-    constructor({ appRootDirPath, fsOperationQueue, messageSender, }: {
+    private readonly draftManager?;
+    private readonly templateRenderer?;
+    private readonly virtualFs;
+    /**
+     * Tracks files that must be read before they can be written.
+     * Used to enforce read-before-write pattern for AI safety.
+     */
+    private readonly requiredReads;
+    constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, }: {
         appRootDirPath: string;
         fsOperationQueue: IOperationQueue;
         messageSender?: (message: any) => Promise<void>;
+        draftInterface?: DraftInterface;
+        templateRenderer?: TemplateRenderer;
+        virtualFileSystem?: VirtualFileSystem;
     });
     readFiles(patterns: string[], globOptions?: GlobOptionsWithFileTypesUnset, enableAppBlacklist?: boolean): Promise<FileArtifact[]>;
     runTypecheck(abortSignal?: AbortSignal): Promise<Record<string, string[]> | null>;
@@ -41,5 +76,174 @@ export declare class AppShell {
      * This is typically called when a draft is rejected to clean up temporary artifacts.
      */
     clearScratchDirectory(): Promise<void>;
+    /**
+     * Reads a single file's content from the application.
+     *
+     * Handles virtual path translation for files managed by the VirtualFileSystem:
+     * - Virtual paths are read via the appropriate handler
+     * - Regular files are read directly from disk
+     *
+     * @param relativePath - The virtual path relative to app root
+     * @param options - Optional read options
+     * @param options.offset - Line number to start reading from (1-indexed)
+     * @param options.limit - Number of lines to read
+     * @returns The file content as a string
+     * @throws Error if file does not exist or cannot be read
+     */
+    readFile(relativePath: string, options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<string>;
+    /**
+     * Internal read implementation (no queue).
+     * Use this from other methods that are already enqueued to avoid deadlock.
+     */
+    private readFileInternal;
+    /**
+     * Writes content to a file as a draft.
+     *
+     * Handles virtual path translation for files managed by the VirtualFileSystem:
+     * - Virtual paths are written via the appropriate handler
+     * - Regular files are written via the draft interface
+     *
+     * @param relativePath - Virtual path relative to app root
+     * @param content - File content to write
+     * @param options - Optional write options
+     * @param options.bypassRequireRead - Skip the read-before-write check (use for new files)
+     * @throws Error if path is blacklisted, restricted, or draft manager not configured
+     * @throws Error if file requires reading first (unless bypassed)
+     */
+    writeFile(relativePath: string, content: string, options?: {
+        bypassRequireRead?: boolean;
+    }): Promise<void>;
+    /**
+     * Internal write implementation.
+     * Called directly by writeFile (no queue wrapper needed since draftInterface queues).
+     */
+    private writeFileInternal;
+    /**
+     * Deletes a file or directory as a draft operation.
+     *
+     * Handles virtual path translation for files managed by the VirtualFileSystem:
+     * - Virtual paths delete via the appropriate handler
+     * - Regular files/directories are deleted via the draft interface
+     *
+     * @param relativePath - Virtual path relative to app root
+     * @throws Error if path is protected or draft manager not configured
+     */
+    deleteFile(relativePath: string): Promise<void>;
+    /**
+     * Internal delete implementation.
+     * Called directly by deleteFile (no queue wrapper needed since draftInterface queues).
+     */
+    private deleteFileInternal;
+    /**
+     * Lists files matching patterns, returning virtual paths.
+     *
+     * Physical files managed by the VirtualFileSystem are converted to
+     * their virtual representations (e.g., apis/MyAPI/api.yaml -> apis/MyAPI.ts).
+     *
+     * @param patterns - Glob patterns to match (defaults to application files)
+     * @param options - Glob options
+     * @returns Array of matching virtual file paths
+     */
+    listFiles(patterns?: string[], options?: GlobOptionsWithFileTypesUnset): Promise<string[]>;
+    /**
+     * Lists files matching patterns with metadata.
+     *
+     * @param patterns - Glob patterns to match (defaults to application files)
+     * @param options - Options including includeMetadata: true
+     * @returns Array of FileMetadata objects
+     */
+    listFiles(patterns?: string[], options?: ListFilesOptions & {
+        includeMetadata: true;
+    }): Promise<FileMetadata[]>;
+    /**
+     * Gets metadata for a list of file paths.
+     *
+     * @param paths - Array of virtual paths to get metadata for
+     * @returns Array of FileMetadata objects (excludes paths that don't exist)
+     */
+    private getFileMetadataList;
+    /**
+     * Gets metadata for a single file path.
+     *
+     * @param virtualPath - The virtual path to get metadata for
+     * @returns FileMetadata or undefined if file doesn't exist
+     */
+    private getFileMetadata;
+    /**
+     * Gets metadata for a virtual API file.
+     * Checks scratch file first (for pending changes), then falls back to YAML.
+     *
+     * @param virtualPath - The virtual API path (e.g., "apis/MyAPI.ts")
+     * @returns FileMetadata or undefined if not found
+     */
+    private getApiFileMetadata;
+    /**
+     * Renames or moves a file.
+     *
+     * Implemented as read + write + delete to work with the draft system.
+     *
+     * @param oldPath - Current virtual path
+     * @param newPath - New virtual path
+     * @throws Error if old file doesn't exist or new path is invalid
+     * @throws Error if old file requires reading first
+     */
+    renameFile(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Checks if there are any pending draft changes.
+     *
+     * @returns true if there are uncommitted draft changes
+     */
+    hasDraftChanges(): Promise<boolean>;
+    /**
+     * Gets a unified diff of pending draft changes.
+     *
+     * @param paths - Optional specific paths to diff. If empty, diffs all changes.
+     * @returns Unified diff string
+     */
+    getDraftDiff(paths?: string[]): Promise<string>;
+    /**
+     * Gets categorized draft changes.
+     *
+     * @returns Object containing arrays of edited, added, and deleted paths
+     */
+    getDraftChanges(): Promise<DraftChanges>;
+    /**
+     * Gets the underlying draft interface for direct access.
+     *
+     * This should only be used for advanced operations that require
+     * direct access to the draft interface. Prefer using the AppShell
+     * methods when possible.
+     *
+     * @internal
+     */
+    getDraftInterface(): DraftInterface | undefined;
+    /**
+     * Check if a file must be read before it can be written.
+     *
+     * @param relativePath - The path to check
+     * @returns true if the file must be read before writing
+     */
+    isReadRequired(relativePath: string): boolean;
+    /**
+     * Mark a file as requiring a read before write.
+     *
+     * Call this when a file has been modified externally (e.g., by lint/format)
+     * to ensure the AI reads the updated content before making further changes.
+     *
+     * @param relativePath - The path to mark as requiring read
+     */
+    requireRead(relativePath: string): void;
+    /**
+     * Mark a file as having been read, allowing subsequent writes.
+     * Called internally after successful read operations.
+     */
+    private markRead;
+    /**
+     * Recursively deletes directory contents by creating draft deletes.
+     */
+    private deleteDirectoryRecursive;
 }
 //# sourceMappingURL=shell.d.ts.map

package/dist/ai-service/app-interface/shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/ai-service/app-interface/shell.ts"],"names":[],"mappings":"AAIA,OAAO,EAAQ,KAAK,6BAA6B,EAAE,MAAM,MAAM,CAAC;AAMhE,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAarE,qBAAa,QAAQ;IACnB,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,aAAa,CAAC,CAAkC;gBAE5C,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,GACd,EAAE;QACD,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,eAAe,CAAC;QAClC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACjD;IAQY,SAAS,CACpB,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,CAAC,EAAE,6BAA6B,EAC3C,kBAAkB,UAAO,GACxB,OAAO,CAAC,YAAY,EAAE,CAAC;IA4Cb,YAAY,CACvB,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAoB9B,qBAAqB,CAChC,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAoCZ,SAAS,CACpB,SAAS,EAAE,MAAM,EAAE,EACnB,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAoBpC,eAAe;IAKT,aAAa,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BvD,wBAAwB,CAAC,WAAW,CAAC,EAAE,WAAW;IA8ClD,uBAAuB,CAClC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,EAClE,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,MAAM,CAAC;IAiGL,iBAAiB,CAC5B,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,WAAW,CAAC;KAC3B,GACA,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA2BjC,qBAAqB,CAChC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;IAeH,WAAW,CAAC,OAAO,EAAE;QAChC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,GAAG,CAAC;KACf,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjB,mDAAmD;IACtC,UAAU,CAAC,YAAY,EAAE,MAAM;IAW5C;;;OAGG;IACU,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAcpD"}
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/ai-service/app-interface/shell.ts"],"names":[],"mappings":"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"}