@superblocksteam/vite-plugin-file-sync 2.0.76 → 2.0.77-next.1

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

@@ -0,0 +1,77 @@
+/**
+ * Constants for AppShell filesystem operations.
+ *
+ * This module contains blacklist patterns, protected paths, and validation
+ * rules used by the AppShell to enforce security constraints on file operations.
+ */
+/**
+ * Files that cannot be deleted, written to, or modified directly.
+ * These are critical configuration files that could break the application.
+ */
+export declare const PROTECTED_EXACT_PATHS: readonly ["package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "tsconfig.json", "turbo.json", "superblocks.json", "vite.config.ts"];
+/**
+ * Directories that cannot be deleted or have their contents directly modified.
+ * - .git: Version control
+ * - node_modules: Dependencies
+ * - .superblocks: Internal system files
+ * - pages: Must use subdirectories, not direct files
+ * - components: Framework internals
+ * - apis: Must use virtual API file interface
+ */
+export declare const PROTECTED_DIRECTORIES: readonly [".git", "node_modules", ".superblocks", "pages", "apis"];
+/**
+ * Regex patterns for protected files (environment files, package manager configs).
+ */
+export declare const PROTECTED_FILE_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
+/**
+ * Clark AI specific folders to blacklist from context.
+ * These are framework/system folders that Clark shouldn't edit or include in prompts.
+ */
+export declare const CLARK_APP_BLACKLIST_PATTERNS: readonly [];
+/**
+ * Consolidated blacklist configuration for file operations.
+ */
+export declare const FILE_OPERATION_BLACKLIST: {
+    readonly exactPaths: readonly ["package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "tsconfig.json", "turbo.json", "superblocks.json", "vite.config.ts"];
+    readonly directories: readonly [".git", "node_modules", ".superblocks", "pages", "apis"];
+    readonly patterns: readonly [RegExp, RegExp, RegExp, RegExp];
+};
+/**
+ * Standard ignore patterns for glob operations.
+ * Files matching these patterns are excluded from file listings.
+ */
+export declare const STANDARD_IGNORE_PATTERNS: readonly ["node_modules/**"];
+/**
+ * File extensions that are considered application code.
+ */
+export declare const APPLICATION_CODE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".css", ".yaml", ".yml"];
+/**
+ * Glob patterns for listing application files.
+ */
+export declare const APPLICATION_FILE_PATTERNS: readonly ["**/*.{ts,tsx,yaml,css}", "package.json"];
+/**
+ * Operation types for validation.
+ */
+export type FileOperation = "read" | "write" | "delete" | "rename" | "list";
+/**
+ * Validation options for file operations.
+ */
+export interface FileOperationValidationOptions {
+    /** Check against blacklist patterns (default: true) */
+    checkBlacklist?: boolean;
+    /** Require file to be read before writing (default: true for write/edit) */
+    checkReadBeforeWrite?: boolean;
+    /** Allow operations on API virtual files (default: false for direct writes) */
+    allowApiFiles?: boolean;
+    /** Allow operations on scope files (default: false) */
+    allowScopeFiles?: boolean;
+    /** Allow operations on package.json (default: false) */
+    allowPackageJson?: boolean;
+    /** Allow direct page paths like pages/xyz.tsx (default: false) */
+    allowDirectPagePath?: boolean;
+}
+/**
+ * Default validation options per operation type.
+ */
+export declare const DEFAULT_VALIDATION_OPTIONS: Record<FileOperation, FileOperationValidationOptions>;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/ai-service/app-interface/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,oJASxB,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,oEAMxB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,uBAAuB,2CAK1B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,4BAA4B,aAAc,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,wBAAwB,8BAA+B,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,2BAA2B,kEAQ9B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,yBAAyB,qDAG5B,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,uDAAuD;IACvD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAC7C,aAAa,EACb,8BAA8B,CA0C/B,CAAC"}

package/dist/ai-service/app-interface/constants.js

@@ -0,0 +1,128 @@
+/**
+ * Constants for AppShell filesystem operations.
+ *
+ * This module contains blacklist patterns, protected paths, and validation
+ * rules used by the AppShell to enforce security constraints on file operations.
+ */
+/**
+ * Files that cannot be deleted, written to, or modified directly.
+ * These are critical configuration files that could break the application.
+ */
+export const PROTECTED_EXACT_PATHS = [
+    "package.json",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "tsconfig.json",
+    "turbo.json",
+    "superblocks.json",
+    "vite.config.ts",
+];
+/**
+ * Directories that cannot be deleted or have their contents directly modified.
+ * - .git: Version control
+ * - node_modules: Dependencies
+ * - .superblocks: Internal system files
+ * - pages: Must use subdirectories, not direct files
+ * - components: Framework internals
+ * - apis: Must use virtual API file interface
+ */
+export const PROTECTED_DIRECTORIES = [
+    ".git",
+    "node_modules",
+    ".superblocks",
+    "pages",
+    "apis",
+];
+/**
+ * Regex patterns for protected files (environment files, package manager configs).
+ */
+export const PROTECTED_FILE_PATTERNS = [
+    /^\.env$/,
+    /^\.env\..+$/,
+    /^\.npmrc$/,
+    /^\.pnpmrc$/,
+];
+/**
+ * Clark AI specific folders to blacklist from context.
+ * These are framework/system folders that Clark shouldn't edit or include in prompts.
+ */
+export const CLARK_APP_BLACKLIST_PATTERNS = [];
+/**
+ * Consolidated blacklist configuration for file operations.
+ */
+export const FILE_OPERATION_BLACKLIST = {
+    exactPaths: PROTECTED_EXACT_PATHS,
+    directories: PROTECTED_DIRECTORIES,
+    patterns: PROTECTED_FILE_PATTERNS,
+};
+/**
+ * Standard ignore patterns for glob operations.
+ * Files matching these patterns are excluded from file listings.
+ */
+export const STANDARD_IGNORE_PATTERNS = ["node_modules/**"];
+/**
+ * File extensions that are considered application code.
+ */
+export const APPLICATION_CODE_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".css",
+    ".yaml",
+    ".yml",
+];
+/**
+ * Glob patterns for listing application files.
+ */
+export const APPLICATION_FILE_PATTERNS = [
+    "**/*.{ts,tsx,yaml,css}",
+    "package.json",
+];
+/**
+ * Default validation options per operation type.
+ */
+export const DEFAULT_VALIDATION_OPTIONS = {
+    read: {
+        checkBlacklist: false,
+        checkReadBeforeWrite: false,
+        allowApiFiles: true,
+        allowScopeFiles: true,
+        allowPackageJson: true,
+        allowDirectPagePath: true,
+    },
+    write: {
+        checkBlacklist: true,
+        checkReadBeforeWrite: true,
+        allowApiFiles: false,
+        allowScopeFiles: false,
+        allowPackageJson: false,
+        allowDirectPagePath: false,
+    },
+    delete: {
+        checkBlacklist: true,
+        checkReadBeforeWrite: false,
+        allowApiFiles: true, // API deletion has special handling
+        allowScopeFiles: false,
+        allowPackageJson: false,
+        allowDirectPagePath: true, // Page deletion has special handling
+    },
+    rename: {
+        checkBlacklist: true,
+        checkReadBeforeWrite: false,
+        allowApiFiles: false,
+        allowScopeFiles: false,
+        allowPackageJson: false,
+        allowDirectPagePath: false,
+    },
+    list: {
+        checkBlacklist: false,
+        checkReadBeforeWrite: false,
+        allowApiFiles: true,
+        allowScopeFiles: true,
+        allowPackageJson: true,
+        allowDirectPagePath: true,
+    },
+};
+//# sourceMappingURL=constants.js.map

package/dist/ai-service/app-interface/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/ai-service/app-interface/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,cAAc;IACd,mBAAmB;IACnB,WAAW;IACX,gBAAgB;IAChB,eAAe;IACf,YAAY;IACZ,kBAAkB;IAClB,gBAAgB;CACR,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,MAAM;IACN,cAAc;IACd,cAAc;IACd,OAAO;IACP,MAAM;CACE,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS;IACT,aAAa;IACb,WAAW;IACX,YAAY;CACJ,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAW,CAAC;AAExD;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,UAAU,EAAE,qBAAqB;IACjC,WAAW,EAAE,qBAAqB;IAClC,QAAQ,EAAE,uBAAuB;CACzB,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,iBAAiB,CAAU,CAAC;AAErE;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;CACE,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,wBAAwB;IACxB,cAAc;CACN,CAAC;AAyBX;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAGnC;IACF,IAAI,EAAE;QACJ,cAAc,EAAE,KAAK;QACrB,oBAAoB,EAAE,KAAK;QAC3B,aAAa,EAAE,IAAI;QACnB,eAAe,EAAE,IAAI;QACrB,gBAAgB,EAAE,IAAI;QACtB,mBAAmB,EAAE,IAAI;KAC1B;IACD,KAAK,EAAE;QACL,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,IAAI;QAC1B,aAAa,EAAE,KAAK;QACpB,eAAe,EAAE,KAAK;QACtB,gBAAgB,EAAE,KAAK;QACvB,mBAAmB,EAAE,KAAK;KAC3B;IACD,MAAM,EAAE;QACN,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,KAAK;QAC3B,aAAa,EAAE,IAAI,EAAE,oCAAoC;QACzD,eAAe,EAAE,KAAK;QACtB,gBAAgB,EAAE,KAAK;QACvB,mBAAmB,EAAE,IAAI,EAAE,qCAAqC;KACjE;IACD,MAAM,EAAE;QACN,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,KAAK;QAC3B,aAAa,EAAE,KAAK;QACpB,eAAe,EAAE,KAAK;QACtB,gBAAgB,EAAE,KAAK;QACvB,mBAAmB,EAAE,KAAK;KAC3B;IACD,IAAI,EAAE;QACJ,cAAc,EAAE,KAAK;QACrB,oBAAoB,EAAE,KAAK;QAC3B,aAAa,EAAE,IAAI;QACnB,eAAe,EAAE,IAAI;QACrB,gBAAgB,EAAE,IAAI;QACtB,mBAAmB,EAAE,IAAI;KAC1B;CACF,CAAC"}

package/dist/ai-service/app-interface/filesystem/draft-manager.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Draft management wrapper.
+ *
+ * Encapsulates the DraftInterface to provide a clean internal API
+ * for managing draft file operations within the AppShell.
+ * External consumers (tools) should not interact with this directly.
+ */
+import type { DraftInterface } from "../../../draft-interface.js";
+/**
+ * Draft changes categorized by operation type.
+ */
+export interface DraftChanges {
+    /** Files that have been edited (content modified) */
+    edits: string[];
+    /** Files that have been added (new files) */
+    additions: string[];
+    /** Files that have been deleted */
+    deletions: string[];
+}
+/**
+ * Manages draft file operations.
+ *
+ * This class wraps the DraftInterface to provide a simplified API
+ * for the AppShell filesystem operations. It handles all draft
+ * creation, deletion, and query operations internally.
+ */
+export declare class DraftManager {
+    private readonly draftInterface;
+    constructor(draftInterface: DraftInterface);
+    /**
+     * Creates a draft file with the given content.
+     *
+     * This stages a file write that can be committed or discarded.
+     * Parent directories are created automatically.
+     *
+     * @param filePath - Relative path of the file
+     * @param content - Content to write
+     */
+    createDraft(filePath: string, content: string): Promise<void>;
+    /**
+     * Creates a draft marker without content.
+     *
+     * Used to mark a file as having a pending draft without
+     * specifying the content immediately.
+     *
+     * @param filePath - Relative path of the file
+     */
+    createDraftMarker(filePath: string): Promise<void>;
+    /**
+     * Creates a draft deletion for a file.
+     *
+     * This stages a file deletion that can be committed or discarded.
+     *
+     * @param filePath - Relative path of the file to delete
+     */
+    createDraftDelete(filePath: 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 DraftInterface.
+     *
+     * This should only be used for advanced operations that require
+     * direct access to the draft interface. Prefer using the methods
+     * on this class when possible.
+     *
+     * @internal
+     */
+    getInterface(): DraftInterface;
+}
+//# sourceMappingURL=draft-manager.d.ts.map

package/dist/ai-service/app-interface/filesystem/draft-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-manager.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/app-interface/filesystem/draft-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mCAAmC;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,EAAE,cAAc;IAE3D;;;;;;;;OAQG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;;;;;;OAOG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;;;;;OAMG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzC;;;;;OAKG;IACG,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC;IAI9C;;;;;;;;OAQG;IACH,YAAY,IAAI,cAAc;CAG/B"}

package/dist/ai-service/app-interface/filesystem/draft-manager.js

@@ -0,0 +1,91 @@
+/**
+ * Draft management wrapper.
+ *
+ * Encapsulates the DraftInterface to provide a clean internal API
+ * for managing draft file operations within the AppShell.
+ * External consumers (tools) should not interact with this directly.
+ */
+/**
+ * Manages draft file operations.
+ *
+ * This class wraps the DraftInterface to provide a simplified API
+ * for the AppShell filesystem operations. It handles all draft
+ * creation, deletion, and query operations internally.
+ */
+export class DraftManager {
+    draftInterface;
+    constructor(draftInterface) {
+        this.draftInterface = draftInterface;
+    }
+    /**
+     * Creates a draft file with the given content.
+     *
+     * This stages a file write that can be committed or discarded.
+     * Parent directories are created automatically.
+     *
+     * @param filePath - Relative path of the file
+     * @param content - Content to write
+     */
+    async createDraft(filePath, content) {
+        await this.draftInterface.createDraftFile(filePath, content);
+    }
+    /**
+     * Creates a draft marker without content.
+     *
+     * Used to mark a file as having a pending draft without
+     * specifying the content immediately.
+     *
+     * @param filePath - Relative path of the file
+     */
+    async createDraftMarker(filePath) {
+        await this.draftInterface.createDraftMarkerOnly(filePath);
+    }
+    /**
+     * Creates a draft deletion for a file.
+     *
+     * This stages a file deletion that can be committed or discarded.
+     *
+     * @param filePath - Relative path of the file to delete
+     */
+    async createDraftDelete(filePath) {
+        await this.draftInterface.createDraftDelete(filePath);
+    }
+    /**
+     * Checks if there are any pending draft changes.
+     *
+     * @returns true if there are uncommitted draft changes
+     */
+    async hasDraftChanges() {
+        return await this.draftInterface.hasLocalDraftChanges();
+    }
+    /**
+     * Gets a unified diff of pending draft changes.
+     *
+     * @param paths - Optional specific paths to diff. If empty, diffs all changes.
+     * @returns Unified diff string
+     */
+    async getDraftDiff(paths) {
+        return await this.draftInterface.getDraftDiff(paths ?? []);
+    }
+    /**
+     * Gets categorized draft changes.
+     *
+     * @returns Object containing arrays of edited, added, and deleted paths
+     */
+    async getDraftChanges() {
+        return await this.draftInterface.getDraftChanges();
+    }
+    /**
+     * Gets the underlying DraftInterface.
+     *
+     * This should only be used for advanced operations that require
+     * direct access to the draft interface. Prefer using the methods
+     * on this class when possible.
+     *
+     * @internal
+     */
+    getInterface() {
+        return this.draftInterface;
+    }
+}
+//# sourceMappingURL=draft-manager.js.map

package/dist/ai-service/app-interface/filesystem/draft-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-manager.js","sourceRoot":"","sources":["../../../../src/ai-service/app-interface/filesystem/draft-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,cAA8B;QAA9B,mBAAc,GAAd,cAAc,CAAgB;IAAG,CAAC;IAE/D;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,QAAgB,EAAE,OAAe;QACjD,MAAM,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QACtC,MAAM,IAAI,CAAC,cAAc,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QACtC,MAAM,IAAI,CAAC,cAAc,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,eAAe;QACnB,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,CAAC;IAC1D,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CAAC,KAAgB;QACjC,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,eAAe;QACnB,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,eAAe,EAAE,CAAC;IACrD,CAAC;IAED;;;;;;;;OAQG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/ai-service/app-interface/filesystem/handlers/api-handler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Virtual file handler for API files.
+ *
+ * APIs appear as single TypeScript files (apis/MyAPI.ts) but are stored
+ * as directories containing YAML definitions and step files.
+ */
+import type { FileMetadata, VirtualFileHandler, VirtualPathInfo, VirtualReadOptions, VirtualWriteOptions, VirtualDeleteOptions } from "../virtual-fs-types.js";
+/**
+ * Handler for virtual API files.
+ *
+ * Virtual path: apis/MyAPI.ts
+ * Physical storage: apis/MyAPI/api.yaml + step files
+ * Scratch location: .superblocks/scratch/apis%2FMyAPI.ts
+ */
+export declare class ApiFileHandler implements VirtualFileHandler {
+    readonly type = "api";
+    matches(virtualPath: string): boolean;
+    matchesPhysical(physicalPath: string): boolean;
+    parse(virtualPath: string): VirtualPathInfo | undefined;
+    toVirtualPath(physicalPath: string): string | undefined;
+    read(virtualPath: string, options: VirtualReadOptions): Promise<string | undefined>;
+    write(virtualPath: string, content: string, options: VirtualWriteOptions): Promise<void>;
+    delete(virtualPath: string, options: VirtualDeleteOptions): Promise<string[]>;
+    /**
+     * 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")
+     * @param options - Read options including app root
+     * @returns FileMetadata or undefined if not found
+     */
+    getMetadata(virtualPath: string, options: VirtualReadOptions): Promise<FileMetadata | undefined>;
+    private deleteDirectoryContents;
+}
+//# sourceMappingURL=api-handler.d.ts.map

package/dist/ai-service/app-interface/filesystem/handlers/api-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-handler.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/app-interface/filesystem/handlers/api-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAsBhC;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,kBAAkB;IACvD,QAAQ,CAAC,IAAI,SAAS;IAEtB,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAKrC,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI9C,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAavD,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUjD,IAAI,CACR,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgFxB,KAAK,CACT,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAcV,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC;IA2CpB;;;;;;;OAOG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;YA2CtB,uBAAuB;CAyBtC"}

package/dist/ai-service/app-interface/filesystem/handlers/api-handler.js

@@ -0,0 +1,236 @@
+/**
+ * Virtual file handler for API files.
+ *
+ * APIs appear as single TypeScript files (apis/MyAPI.ts) but are stored
+ * as directories containing YAML definitions and step files.
+ */
+import { readFile, mkdir, writeFile, access, rm, readdir, stat, } from "node:fs/promises";
+import * as path from "node:path";
+import { Paths } from "../../../const.js";
+import { YamlToApiBuilderTransformer } from "../../../transform/api-builder/to-sdk-transformer.js";
+import { matchPath, matchMultiplePaths, renderPath, applyFileTransformations, } from "../../../transform/shared.js";
+// Path matchers
+const generatedApisMatch = matchPath(Paths.GeneratedApis);
+const apiArtifactsMatchRaw = matchMultiplePaths("apis/:apiName", "apis/:apiName/", "apis/:apiName/**");
+/**
+ * Matches physical API artifact paths (directories and files inside API dirs).
+ * Excludes virtual paths like apis/MyAPI.ts.
+ */
+function matchPhysicalApiPath(physicalPath) {
+    const match = apiArtifactsMatchRaw(physicalPath);
+    if (match.matched && !match.params.apiName.endsWith(".ts")) {
+        return match;
+    }
+    return { matched: false };
+}
+/**
+ * Handler for virtual API files.
+ *
+ * Virtual path: apis/MyAPI.ts
+ * Physical storage: apis/MyAPI/api.yaml + step files
+ * Scratch location: .superblocks/scratch/apis%2FMyAPI.ts
+ */
+export class ApiFileHandler {
+    type = "api";
+    matches(virtualPath) {
+        const match = generatedApisMatch(virtualPath);
+        return match.matched && match.params.apiName.endsWith(".ts");
+    }
+    matchesPhysical(physicalPath) {
+        return matchPhysicalApiPath(physicalPath).matched;
+    }
+    parse(virtualPath) {
+        const match = generatedApisMatch(virtualPath);
+        if (match.matched && match.params.apiName.endsWith(".ts")) {
+            return {
+                type: this.type,
+                params: {
+                    apiName: path.basename(match.params.apiName, ".ts"),
+                },
+            };
+        }
+        return undefined;
+    }
+    toVirtualPath(physicalPath) {
+        const match = matchPhysicalApiPath(physicalPath);
+        if (match.matched) {
+            return renderPath(Paths.GeneratedApis, {
+                apiName: `${match.params.apiName}.ts`,
+            });
+        }
+        return undefined;
+    }
+    async read(virtualPath, options) {
+        const info = this.parse(virtualPath);
+        if (!info)
+            return undefined;
+        const { appRootDirPath, templateRenderer, entityNames = [] } = options;
+        const { apiName } = info.params;
+        if (!apiName)
+            return undefined;
+        // Build paths
+        const scratchPath = renderPath(Paths.Scratch, { path: virtualPath });
+        const fullScratchPath = path.join(appRootDirPath, scratchPath);
+        const yamlPath = renderPath(Paths.ApiYamls, { apiName });
+        const fullYamlPath = path.join(appRootDirPath, yamlPath);
+        // Check if both scratch and YAML exist, and compare timestamps
+        // If YAML is newer than scratch, the scratch is stale (user made manual edits)
+        let scratchExists = false;
+        let scratchMtime;
+        let yamlExists = false;
+        let yamlMtime;
+        try {
+            const scratchStat = await stat(fullScratchPath);
+            scratchExists = true;
+            scratchMtime = scratchStat.mtime;
+        }
+        catch {
+            // Scratch doesn't exist
+        }
+        try {
+            const yamlStat = await stat(fullYamlPath);
+            yamlExists = true;
+            yamlMtime = yamlStat.mtime;
+        }
+        catch {
+            // YAML doesn't exist
+        }
+        // If scratch exists and is newer than YAML (or YAML doesn't exist), use scratch
+        const scratchIsFresh = scratchExists &&
+            scratchMtime &&
+            (!yamlExists || !yamlMtime || scratchMtime >= yamlMtime);
+        if (scratchIsFresh) {
+            return await readFile(fullScratchPath, "utf-8");
+        }
+        // YAML doesn't exist and scratch is stale or missing
+        if (!yamlExists) {
+            return undefined;
+        }
+        if (!templateRenderer) {
+            throw new Error("TemplateRenderer is required to generate API content from YAML");
+        }
+        // Generate from YAML (scratch is stale or doesn't exist)
+        const yamlArtifact = {
+            type: "file",
+            filePath: yamlPath,
+            content: "",
+        };
+        const [sdkArtifact] = await applyFileTransformations([yamlArtifact], [
+            new YamlToApiBuilderTransformer({
+                appRootDirPath,
+                entityNames,
+                skipCleanup: true,
+                templateRenderer,
+            }),
+        ]);
+        return sdkArtifact?.content;
+    }
+    async write(virtualPath, content, options) {
+        const info = this.parse(virtualPath);
+        if (!info) {
+            throw new Error(`Invalid API path: ${virtualPath}`);
+        }
+        const { appRootDirPath } = options;
+        const scratchPath = renderPath(Paths.Scratch, { path: virtualPath });
+        const fullScratchPath = path.join(appRootDirPath, scratchPath);
+        await mkdir(path.dirname(fullScratchPath), { recursive: true });
+        await writeFile(fullScratchPath, content, "utf-8");
+    }
+    async delete(virtualPath, options) {
+        const info = this.parse(virtualPath);
+        if (!info) {
+            throw new Error(`Invalid API path: ${virtualPath}`);
+        }
+        const { appRootDirPath, createDraftDelete } = options;
+        const { apiName } = info.params;
+        if (!apiName) {
+            throw new Error(`Missing apiName in parsed path: ${virtualPath}`);
+        }
+        const deletedPaths = [];
+        // Delete API directory contents
+        const apiDirPath = renderPath(Paths.GeneratedApis, { apiName });
+        const absoluteApiDirPath = path.join(appRootDirPath, apiDirPath);
+        try {
+            await access(absoluteApiDirPath);
+            await this.deleteDirectoryContents(absoluteApiDirPath, appRootDirPath, createDraftDelete, deletedPaths);
+            await rm(absoluteApiDirPath, { recursive: true, force: true });
+        }
+        catch {
+            // API directory doesn't exist
+        }
+        // Delete scratch file if it exists
+        const scratchPath = renderPath(Paths.Scratch, { path: virtualPath });
+        try {
+            await createDraftDelete(scratchPath);
+            deletedPaths.push(scratchPath);
+        }
+        catch {
+            // Scratch file doesn't exist
+        }
+        return deletedPaths;
+    }
+    /**
+     * 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")
+     * @param options - Read options including app root
+     * @returns FileMetadata or undefined if not found
+     */
+    async getMetadata(virtualPath, options) {
+        const info = this.parse(virtualPath);
+        if (!info)
+            return undefined;
+        const { appRootDirPath } = options;
+        const { apiName } = info.params;
+        if (!apiName)
+            return undefined;
+        // Check scratch file first (for pending changes)
+        const scratchPath = renderPath(Paths.Scratch, { path: virtualPath });
+        const fullScratchPath = path.join(appRootDirPath, scratchPath);
+        try {
+            const stats = await stat(fullScratchPath);
+            return {
+                path: virtualPath,
+                size: stats.size,
+                mtime: stats.mtime,
+                isDirectory: false,
+                isFile: true,
+            };
+        }
+        catch {
+            // Fall back to YAML file
+        }
+        // Check YAML file
+        const yamlPath = renderPath(Paths.ApiYamls, { apiName });
+        const fullYamlPath = path.join(appRootDirPath, yamlPath);
+        try {
+            const stats = await stat(fullYamlPath);
+            return {
+                path: virtualPath,
+                size: stats.size,
+                mtime: stats.mtime,
+                isDirectory: false,
+                isFile: true,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async deleteDirectoryContents(dirPath, appRootDirPath, createDraftDelete, deletedPaths) {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            const relativePath = path.relative(appRootDirPath, fullPath);
+            if (entry.isDirectory()) {
+                await this.deleteDirectoryContents(fullPath, appRootDirPath, createDraftDelete, deletedPaths);
+            }
+            else {
+                await createDraftDelete(relativePath);
+                deletedPaths.push(relativePath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=api-handler.js.map