@apicircle/shared 1.0.8 → 1.1.0

package/dist/index.d.cts

@@ -132,15 +132,26 @@ interface MockResponseConfig {
     delayMs?: number;
     /**
      * Optional response-shape multipliers. At runtime, each multiplier reads a
-     * value from the request (a query/path/header param or a JSON-path slice
-     * of the request body) and repeats the array element at `targetJsonPath`
-     * inside the response body that many times. Used to drive page-size
-     * aware mock responses without templating the body manually.
+     * value from the request (a query/path/header param or a JSON-path slice of
+     * the request body) and repeats the array element at `targetJsonPath` inside
+     * the response body that many times. Used to drive page-size aware mock
+     * responses without templating the body manually.
      *
-     * Only fires when `body.type === 'json'`; ignored otherwise.
+     * The persisted shape is an array so the feature can grow to N multipliers
+     * without a schema migration. For now the authoring surfaces (editors, MCP
+     * tools) cap the list at {@link MAX_RESPONSE_MULTIPLIERS}; the runtime applies
+     * every entry it finds (so a future cap bump — or a hand-edit — needs no
+     * engine change). Only fires when `body.type === 'json'`; ignored otherwise.
      */
     multipliers?: MockResponseMultiplier[];
 }
+/**
+ * How many response multipliers the authoring surfaces (desktop/web editor,
+ * VS Code lenses, MCP tools) allow per response. The persisted shape is an
+ * array, so raising this to N — or removing the gate — is the ONLY change
+ * needed to support multiple multipliers; no data migration, no engine change.
+ */
+declare const MAX_RESPONSE_MULTIPLIERS = 1;
 type MockMultiplierSourceKind = 'query' | 'pathParam' | 'header' | 'body-json-path';
 interface MockMultiplierSource {
     kind: MockMultiplierSourceKind;
@@ -227,6 +238,14 @@ interface MockResponseRule {
     when: MockConditionClause[];
     response: MockResponseConfig;
 }
+/**
+ * How many `when` clauses the authoring surfaces (VS Code lenses, desktop/web
+ * editor, MCP tools) allow per response rule. The persisted shape is an array
+ * and the runtime AND-combines every clause it finds, so raising this to N — or
+ * removing the gate — is the ONLY change needed to support multi-clause rules;
+ * no data migration, no engine change. Mirrors {@link MAX_RESPONSE_MULTIPLIERS}.
+ */
+declare const MAX_RESPONSE_RULE_CONDITIONS = 1;
 interface MockEndpoint {
     /** Stable id; survives spec re-parses so per-endpoint overrides keep matching. */
     id: string;
@@ -486,6 +505,38 @@ interface GlobalGraphQL {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Pointer to a verified-good copy of a Global File Asset's bytes on a
+ * specific Git ref. Each asset can carry up to two of these — one for
+ * the consumer's working branch and one for the base branch the working
+ * branch was forked from — and the cleanup invariant drops the working
+ * ref once the base ref holds the same blob (single source of truth).
+ *
+ * Populated lazily — never at upload time. The first push promotes the
+ * pending upload to `workingBranchRef`; the next refresh after the PR
+ * merges promotes to `baseBranchRef`. See
+ * docs/architecture/platform.md for the full state machine.
+ */
+interface AssetGitRef {
+    /** Branch the asset is known to live on. */
+    branchName: string;
+    /**
+     * GitHub blob SHA at the most recent successful verification. Drives
+     * the cleanup invariant — when both refs return the same `blobSha` the
+     * working ref is redundant and gets dropped. Optional because legacy
+     * entries persisted before this field existed; consumers treat absent
+     * as "not yet verified."
+     */
+    blobSha?: string;
+    /**
+     * Commit SHA the ref was first recorded at. Used for display
+     * ("On main · since v2.3.1") and for the "branch retargeted" detection
+     * path where the same branchName resolves to a different blob.
+     */
+    commitSha?: string;
+    /** ISO timestamp of the last successful read of this ref. */
+    verifiedAt: string;
+}
 interface GlobalFileAsset {
     id: string;
     name: string;
@@ -497,6 +548,55 @@ interface GlobalFileAsset {
     sha256?: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Provenance pointer to the asset's bytes on the consumer's currently
+     * connected working branch. Set by the push flow after `updateRef`
+     * resolves with the GitHub blob sha. Dropped by the cleanup invariant
+     * when `baseBranchRef` holds the same blob. Optional — pre-1.0.9 docs
+     * and freshly-uploaded-but-unpushed assets leave it `undefined`.
+     */
+    workingBranchRef?: AssetGitRef | null;
+    /**
+     * Provenance pointer to the asset's bytes on the base branch the
+     * working branch was forked from (usually `main`). Set by the refresh
+     * verification probe once the PR merges. Optional — assets that have
+     * never been merged leave it `undefined`.
+     */
+    baseBranchRef?: AssetGitRef | null;
+}
+/**
+ * Local-only buffer recording an asset whose bytes are in IDB but have
+ * not yet been pushed to any Git ref. Keyed by `globalFileAssetId` so
+ * the desktop / web can render an "Uploaded locally" state pill and the
+ * push flow knows which slots still need to be uploaded as blobs. Dropped
+ * by the push flow after `globalAsset.markPushed` lands.
+ */
+interface PendingFileUpload {
+    slotId: string;
+    filename: string;
+    mimeType: string;
+    sha256: string;
+    size: number;
+    /** ISO timestamp the file was dropped into the studio. */
+    queuedAt: string;
+}
+/**
+ * Where a Global File Asset is referenced inside the current synced doc.
+ * Recomputed by `assetUsageAggregator` after every `commitSynced`. Used
+ * to surface "Used in N places" in the Global Assets panel, the form-data
+ * row, the binary body, and the mock-response editors, and to flag
+ * zero-use orphans for one-click cleanup.
+ */
+interface AssetUsage {
+    /** Request ids whose body binds this asset. */
+    requests: string[];
+    /** Mock endpoints whose responses bind this asset. */
+    mockEndpoints: Array<{
+        mockId: string;
+        endpointId: string;
+    }>;
+    /** Total reference count — denormalised for cheap badge rendering. */
+    total: number;
 }
 type RequestAuth = {
     type: 'none';
@@ -677,7 +777,7 @@ interface LocalAttachmentCacheEntry {
     /**
      * Local-only path or storage URI where this device can read the bytes for
      * execution. Browser builds use an IndexedDB URI; CLI runs use an absolute
-     * filesystem path under `.apicircle/attachments/`.
+     * filesystem path under `.apicircle/workspace-<id>/attachments/`.
      */
     localPath: string;
     storage: 'indexeddb' | 'filesystem';
@@ -754,6 +854,10 @@ interface LinkedWorkspace {
     kind: 'private' | 'public';
     name: string;
     description?: string;
+    /** The remote workspace's `workspaceId` (from the source's registry).
+     *  Needed to resolve per-workspace paths (attachments, workspace.json)
+     *  when fetching from the source repo. */
+    sourceWorkspaceId: string;
     source: {
         provider: 'github';
         repoFullName: string;
@@ -900,6 +1004,39 @@ interface WorkspaceLocal {
      * eviction.
      */
     snapshots: WorkspaceSnapshotLedger;
+    /**
+     * Pre-push buffer for Global File Asset bytes. Each entry mirrors the
+     * IDB attachment record (which stays the authoritative byte store) but
+     * is keyed by `globalFileAssetId` instead of `slotId`, making it easy
+     * for the push flow + the status-pill UI to ask "is this asset still
+     * pending upload?" without scanning IDB. Dropped per-asset after the
+     * push promotes the asset to `workingBranchRef`.
+     */
+    pendingFileUploads?: Record<string, PendingFileUpload>;
+    /**
+     * Cross-cutting reference index for Global File Assets. Recomputed by
+     * `assetUsageAggregator` whenever `commitSynced` runs, mirroring the
+     * `secretIndex.entries[].usedIn` pattern. Local-only because it's pure
+     * cache — the truth lives in `synced.collections.requests` and
+     * `synced.mockServers`.
+     */
+    assetUsageIndex?: Record<string, AssetUsage>;
+    /**
+     * Slot ids whose attachment blob needs to be DELETED from the working
+     * branch on the next push. Queued by `removeGlobalFileAsset` (and the
+     * headless `globalAsset.removeFile` patch) when the asset being
+     * deleted had any push provenance (`workingBranchRef` or
+     * `baseBranchRef`). The push emits
+     * `{path: '.apicircle/workspace-<id>/attachments/<slotId>', sha: null}`
+     * tree entries layered over `base_tree`, which GitHub treats as
+     * deletions. After a successful push, the queue is cleared — the
+     * deletion is durable on the working branch, and the eventual PR
+     * merge propagates it to the base branch.
+     *
+     * Without this queue, the asset would be removed from `workspace.json`
+     * but the orphan blob would persist on the remote tree forever.
+     */
+    pendingAttachmentDeletes?: string[];
 }
 interface WorkspaceLocalSettings {
     validateOnSend: boolean;
@@ -1283,7 +1420,7 @@ declare const REQUEST_AUTH_TYPES: ReadonlyArray<RequestAuthType>;
  * clients can group them in their UI. Keep in sync with the registry in
  * `packages/mcp-server/src/tools/registry.ts`.
  */
-type McpToolName = 'import.curl' | 'import.openapi' | 'import.postman' | 'import.insomnia' | 'import.har' | 'generate.code' | 'workspace.list' | 'workspace.read' | 'workspace.write' | 'request.create' | 'request.read' | 'request.update' | 'request.delete' | 'folder.create' | 'folder.read' | 'folder.update' | 'folder.delete' | 'folder.export_json' | 'folder.import_json' | 'environment.create' | 'environment.read' | 'environment.update' | 'environment.delete' | 'environment.set_active' | 'environment.set_priority' | 'environment.export' | 'environment.import' | 'plan.create' | 'plan.run' | 'plan.read' | 'plan.update' | 'plan.delete' | 'plan.add_step' | 'plan.remove_step' | 'plan.reorder_steps' | 'plan.set_variables' | 'assertion.create' | 'assertion.read' | 'assertion.update' | 'assertion.delete' | 'history.list_runs' | 'history.get_run' | 'history.delete_run' | 'history.purge_by_age' | 'codebase.extract_collection' | 'prompt.create_environment' | 'prompt.create_assertion' | 'prompt.create_plan' | 'prompt.create_request' | 'prompt.update_request' | 'prompt.create_folder_tree' | 'prompt.add_plan_steps' | 'prompt.set_plan_variables' | 'prompt.create_mock_server' | 'prompt.add_mock_endpoint' | 'prompt.set_endpoint_validation_rules' | 'prompt.set_endpoint_response_rules' | 'prompt.set_endpoint_multipliers' | 'mock.create_from_openapi' | 'mock.create_from_postman' | 'mock.create_from_insomnia' | 'mock.create_manual' | 'mock.list' | 'mock.list_endpoints' | 'mock.start' | 'mock.stop' | 'mock.delete' | 'mock.add_endpoint' | 'mock.update_endpoint' | 'mock.delete_endpoint' | 'mock.set_validation_rules' | 'mock.set_response_rules' | 'mock.set_multipliers' | 'mock.import_postman_mock_collection';
+type McpToolName = 'import.curl' | 'import.openapi' | 'import.postman' | 'import.insomnia' | 'import.har' | 'generate.code' | 'workspace.list' | 'workspace.read' | 'workspace.write' | 'request.create' | 'request.read' | 'request.update' | 'request.delete' | 'folder.create' | 'folder.read' | 'folder.update' | 'folder.delete' | 'folder.export_json' | 'folder.import_json' | 'environment.create' | 'environment.read' | 'environment.update' | 'environment.delete' | 'environment.set_active' | 'environment.set_priority' | 'environment.export' | 'environment.import' | 'plan.create' | 'plan.run' | 'plan.read' | 'plan.update' | 'plan.delete' | 'plan.add_step' | 'plan.remove_step' | 'plan.reorder_steps' | 'plan.set_variables' | 'assertion.create' | 'assertion.read' | 'assertion.update' | 'assertion.delete' | 'history.list_runs' | 'history.get_run' | 'history.delete_run' | 'history.purge_by_age' | 'codebase.extract_collection' | 'prompt.create_environment' | 'prompt.create_assertion' | 'prompt.create_plan' | 'prompt.create_request' | 'prompt.update_request' | 'prompt.create_folder_tree' | 'prompt.add_plan_steps' | 'prompt.set_plan_variables' | 'prompt.create_mock_server' | 'prompt.add_mock_endpoint' | 'prompt.set_endpoint_validation_rules' | 'prompt.set_endpoint_response_rules' | 'prompt.set_endpoint_multipliers' | 'prompt.set_endpoint_request_schema' | 'assets.list_files' | 'assets.create_file' | 'assets.update_file' | 'assets.delete_file' | 'mock.create_from_openapi' | 'mock.create_from_postman' | 'mock.create_from_insomnia' | 'mock.create_manual' | 'mock.list' | 'mock.list_endpoints' | 'mock.start' | 'mock.stop' | 'mock.delete' | 'mock.add_endpoint' | 'mock.update_endpoint' | 'mock.delete_endpoint' | 'mock.set_validation_rules' | 'mock.set_response_rules' | 'mock.set_multipliers' | 'mock.set_request_schema' | 'mock.set_default_port' | 'mock.import_postman_mock_collection' | 'release.list' | 'release.publish' | 'release.deprecate' | 'release.yank' | 'linked.list' | 'linked.get' | 'linked.set_config' | 'linked.unlink' | 'linked.link' | 'linked.refresh' | 'release.tag' | 'repo.set_topics' | 'marketplace.search';
 interface McpError {
     code: 'invalid_input' | 'not_found' | 'conflict' | 'unsupported' | 'internal';
     message: string;
@@ -1292,4 +1429,4 @@ interface McpError {
 /** Helper: full enumeration of tool names — useful for the docs / config UIs. */
 declare const MCP_TOOL_NAMES: ReadonlyArray<McpToolName>;
 
-export { type Assertion, type AttachmentRef, type AwsSigV4Auth, type BodyType, type ConnectedRepo, type ContextExtraction, DEFAULT_WORKSPACE_NAME, type DigestAuth, type EnvPriorityRef, type Environment, type EnvironmentVariable, type EnvironmentVariableOverride, type ExecutionPlan, FONT_SIZE_PERCENT_DEFAULT, FONT_SIZE_PERCENT_MAX, FONT_SIZE_PERCENT_MIN, FONT_SIZE_PERCENT_STEP, type Folder, type FolderNode, type FontFamilyId, type FormDataRow, type GitHubSession, type GlobalFileAsset, type GlobalGraphQL, type GlobalSchema, type HawkAuth, type HttpMethod, type JwtBearerAuth, type LinkedSnapshot, type LinkedWorkspace, type LocalAttachmentCacheEntry, MCP_TOOL_NAMES, type McpError, type McpToolName, type MockConditionClause, type MockConditionOp, type MockConditionScope, type MockEndpoint, type MockMultiplierSource, type MockMultiplierSourceKind, type MockParamDef, type MockRequestSchema, type MockResponseBody, type MockResponseBodyType, type MockResponseConfig, type MockResponseMultiplier, type MockResponseRule, type MockRuntime, type MockRuntimeEntry, type MockServer, type MockServerSource, type MockValidationKind, type MockValidationRule, type NtlmAuth, type OAuth2AuthCodeAuth, type OAuth2ClientCredentialsAuth, type OAuth2DeviceAuth, type OAuth2ImplicitAuth, type OAuth2PasswordAuth, type OAuth2PkceAuth, type OAuth2TokenState, type PanelId, type PlanRun, REQUEST_AUTH_TYPES, RUN_BODY_PREVIEW_LIMIT, type ReleaseHistory, type ReleaseVersion, type Request, type RequestAuth, type RequestAuthType, type RequestBody, type RequestOverride, type RequestOverridePatch, type RequestRun, type RetiredBranch, type SecretCryptoMeta, type SecretEntry, type SecretIndex, type SecretKeyMeta, type SecretUsage, type SyncSnapshot, type ThemeId, type ValidationResult, type WorkingBranch, type WorkspaceLocal, type WorkspaceSnapshot, type WorkspaceSnapshotLedger, type WorkspaceSnapshotTrigger, type WorkspaceSynced, coerceMockResponseBodyTypeForStatus, defaultAuthFor, envPriorityDisplayName, envPriorityKey, envPriorityRefEqual, formatBytes, generateId, getAllowedMockResponseBodyTypes, makeDefaultMockResponse, makeDefaultMockResponseBody, makeDefaultRequestSchema, normalizeAuth, parseEnvPriorityKey, safeExternalHref, utf8ByteLength, validateAwsRegion, validateEnvVarName, validateHttpHeaderName, validateJsonPath, validateJsonString, validateMockPath, validatePRTitle, validatePlanName, validatePositiveDuration, validateRegex, validateUrl };
+export { type Assertion, type AssetGitRef, type AssetUsage, type AttachmentRef, type AwsSigV4Auth, type BodyType, type ConnectedRepo, type ContextExtraction, DEFAULT_WORKSPACE_NAME, type DigestAuth, type EnvPriorityRef, type Environment, type EnvironmentVariable, type EnvironmentVariableOverride, type ExecutionPlan, FONT_SIZE_PERCENT_DEFAULT, FONT_SIZE_PERCENT_MAX, FONT_SIZE_PERCENT_MIN, FONT_SIZE_PERCENT_STEP, type Folder, type FolderNode, type FontFamilyId, type FormDataRow, type GitHubSession, type GlobalFileAsset, type GlobalGraphQL, type GlobalSchema, type HawkAuth, type HttpMethod, type JwtBearerAuth, type LinkedSnapshot, type LinkedWorkspace, type LocalAttachmentCacheEntry, MAX_RESPONSE_MULTIPLIERS, MAX_RESPONSE_RULE_CONDITIONS, MCP_TOOL_NAMES, type McpError, type McpToolName, type MockConditionClause, type MockConditionOp, type MockConditionScope, type MockEndpoint, type MockMultiplierSource, type MockMultiplierSourceKind, type MockParamDef, type MockRequestSchema, type MockResponseBody, type MockResponseBodyType, type MockResponseConfig, type MockResponseMultiplier, type MockResponseRule, type MockRuntime, type MockRuntimeEntry, type MockServer, type MockServerSource, type MockValidationKind, type MockValidationRule, type NtlmAuth, type OAuth2AuthCodeAuth, type OAuth2ClientCredentialsAuth, type OAuth2DeviceAuth, type OAuth2ImplicitAuth, type OAuth2PasswordAuth, type OAuth2PkceAuth, type OAuth2TokenState, type PanelId, type PendingFileUpload, type PlanRun, REQUEST_AUTH_TYPES, RUN_BODY_PREVIEW_LIMIT, type ReleaseHistory, type ReleaseVersion, type Request, type RequestAuth, type RequestAuthType, type RequestBody, type RequestOverride, type RequestOverridePatch, type RequestRun, type RetiredBranch, type SecretCryptoMeta, type SecretEntry, type SecretIndex, type SecretKeyMeta, type SecretUsage, type SyncSnapshot, type ThemeId, type ValidationResult, type WorkingBranch, type WorkspaceLocal, type WorkspaceSnapshot, type WorkspaceSnapshotLedger, type WorkspaceSnapshotTrigger, type WorkspaceSynced, coerceMockResponseBodyTypeForStatus, defaultAuthFor, envPriorityDisplayName, envPriorityKey, envPriorityRefEqual, formatBytes, generateId, getAllowedMockResponseBodyTypes, makeDefaultMockResponse, makeDefaultMockResponseBody, makeDefaultRequestSchema, normalizeAuth, parseEnvPriorityKey, safeExternalHref, utf8ByteLength, validateAwsRegion, validateEnvVarName, validateHttpHeaderName, validateJsonPath, validateJsonString, validateMockPath, validatePRTitle, validatePlanName, validatePositiveDuration, validateRegex, validateUrl };

package/dist/index.d.ts

@@ -132,15 +132,26 @@ interface MockResponseConfig {
     delayMs?: number;
     /**
      * Optional response-shape multipliers. At runtime, each multiplier reads a
-     * value from the request (a query/path/header param or a JSON-path slice
-     * of the request body) and repeats the array element at `targetJsonPath`
-     * inside the response body that many times. Used to drive page-size
-     * aware mock responses without templating the body manually.
+     * value from the request (a query/path/header param or a JSON-path slice of
+     * the request body) and repeats the array element at `targetJsonPath` inside
+     * the response body that many times. Used to drive page-size aware mock
+     * responses without templating the body manually.
      *
-     * Only fires when `body.type === 'json'`; ignored otherwise.
+     * The persisted shape is an array so the feature can grow to N multipliers
+     * without a schema migration. For now the authoring surfaces (editors, MCP
+     * tools) cap the list at {@link MAX_RESPONSE_MULTIPLIERS}; the runtime applies
+     * every entry it finds (so a future cap bump — or a hand-edit — needs no
+     * engine change). Only fires when `body.type === 'json'`; ignored otherwise.
      */
     multipliers?: MockResponseMultiplier[];
 }
+/**
+ * How many response multipliers the authoring surfaces (desktop/web editor,
+ * VS Code lenses, MCP tools) allow per response. The persisted shape is an
+ * array, so raising this to N — or removing the gate — is the ONLY change
+ * needed to support multiple multipliers; no data migration, no engine change.
+ */
+declare const MAX_RESPONSE_MULTIPLIERS = 1;
 type MockMultiplierSourceKind = 'query' | 'pathParam' | 'header' | 'body-json-path';
 interface MockMultiplierSource {
     kind: MockMultiplierSourceKind;
@@ -227,6 +238,14 @@ interface MockResponseRule {
     when: MockConditionClause[];
     response: MockResponseConfig;
 }
+/**
+ * How many `when` clauses the authoring surfaces (VS Code lenses, desktop/web
+ * editor, MCP tools) allow per response rule. The persisted shape is an array
+ * and the runtime AND-combines every clause it finds, so raising this to N — or
+ * removing the gate — is the ONLY change needed to support multi-clause rules;
+ * no data migration, no engine change. Mirrors {@link MAX_RESPONSE_MULTIPLIERS}.
+ */
+declare const MAX_RESPONSE_RULE_CONDITIONS = 1;
 interface MockEndpoint {
     /** Stable id; survives spec re-parses so per-endpoint overrides keep matching. */
     id: string;
@@ -486,6 +505,38 @@ interface GlobalGraphQL {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Pointer to a verified-good copy of a Global File Asset's bytes on a
+ * specific Git ref. Each asset can carry up to two of these — one for
+ * the consumer's working branch and one for the base branch the working
+ * branch was forked from — and the cleanup invariant drops the working
+ * ref once the base ref holds the same blob (single source of truth).
+ *
+ * Populated lazily — never at upload time. The first push promotes the
+ * pending upload to `workingBranchRef`; the next refresh after the PR
+ * merges promotes to `baseBranchRef`. See
+ * docs/architecture/platform.md for the full state machine.
+ */
+interface AssetGitRef {
+    /** Branch the asset is known to live on. */
+    branchName: string;
+    /**
+     * GitHub blob SHA at the most recent successful verification. Drives
+     * the cleanup invariant — when both refs return the same `blobSha` the
+     * working ref is redundant and gets dropped. Optional because legacy
+     * entries persisted before this field existed; consumers treat absent
+     * as "not yet verified."
+     */
+    blobSha?: string;
+    /**
+     * Commit SHA the ref was first recorded at. Used for display
+     * ("On main · since v2.3.1") and for the "branch retargeted" detection
+     * path where the same branchName resolves to a different blob.
+     */
+    commitSha?: string;
+    /** ISO timestamp of the last successful read of this ref. */
+    verifiedAt: string;
+}
 interface GlobalFileAsset {
     id: string;
     name: string;
@@ -497,6 +548,55 @@ interface GlobalFileAsset {
     sha256?: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Provenance pointer to the asset's bytes on the consumer's currently
+     * connected working branch. Set by the push flow after `updateRef`
+     * resolves with the GitHub blob sha. Dropped by the cleanup invariant
+     * when `baseBranchRef` holds the same blob. Optional — pre-1.0.9 docs
+     * and freshly-uploaded-but-unpushed assets leave it `undefined`.
+     */
+    workingBranchRef?: AssetGitRef | null;
+    /**
+     * Provenance pointer to the asset's bytes on the base branch the
+     * working branch was forked from (usually `main`). Set by the refresh
+     * verification probe once the PR merges. Optional — assets that have
+     * never been merged leave it `undefined`.
+     */
+    baseBranchRef?: AssetGitRef | null;
+}
+/**
+ * Local-only buffer recording an asset whose bytes are in IDB but have
+ * not yet been pushed to any Git ref. Keyed by `globalFileAssetId` so
+ * the desktop / web can render an "Uploaded locally" state pill and the
+ * push flow knows which slots still need to be uploaded as blobs. Dropped
+ * by the push flow after `globalAsset.markPushed` lands.
+ */
+interface PendingFileUpload {
+    slotId: string;
+    filename: string;
+    mimeType: string;
+    sha256: string;
+    size: number;
+    /** ISO timestamp the file was dropped into the studio. */
+    queuedAt: string;
+}
+/**
+ * Where a Global File Asset is referenced inside the current synced doc.
+ * Recomputed by `assetUsageAggregator` after every `commitSynced`. Used
+ * to surface "Used in N places" in the Global Assets panel, the form-data
+ * row, the binary body, and the mock-response editors, and to flag
+ * zero-use orphans for one-click cleanup.
+ */
+interface AssetUsage {
+    /** Request ids whose body binds this asset. */
+    requests: string[];
+    /** Mock endpoints whose responses bind this asset. */
+    mockEndpoints: Array<{
+        mockId: string;
+        endpointId: string;
+    }>;
+    /** Total reference count — denormalised for cheap badge rendering. */
+    total: number;
 }
 type RequestAuth = {
     type: 'none';
@@ -677,7 +777,7 @@ interface LocalAttachmentCacheEntry {
     /**
      * Local-only path or storage URI where this device can read the bytes for
      * execution. Browser builds use an IndexedDB URI; CLI runs use an absolute
-     * filesystem path under `.apicircle/attachments/`.
+     * filesystem path under `.apicircle/workspace-<id>/attachments/`.
      */
     localPath: string;
     storage: 'indexeddb' | 'filesystem';
@@ -754,6 +854,10 @@ interface LinkedWorkspace {
     kind: 'private' | 'public';
     name: string;
     description?: string;
+    /** The remote workspace's `workspaceId` (from the source's registry).
+     *  Needed to resolve per-workspace paths (attachments, workspace.json)
+     *  when fetching from the source repo. */
+    sourceWorkspaceId: string;
     source: {
         provider: 'github';
         repoFullName: string;
@@ -900,6 +1004,39 @@ interface WorkspaceLocal {
      * eviction.
      */
     snapshots: WorkspaceSnapshotLedger;
+    /**
+     * Pre-push buffer for Global File Asset bytes. Each entry mirrors the
+     * IDB attachment record (which stays the authoritative byte store) but
+     * is keyed by `globalFileAssetId` instead of `slotId`, making it easy
+     * for the push flow + the status-pill UI to ask "is this asset still
+     * pending upload?" without scanning IDB. Dropped per-asset after the
+     * push promotes the asset to `workingBranchRef`.
+     */
+    pendingFileUploads?: Record<string, PendingFileUpload>;
+    /**
+     * Cross-cutting reference index for Global File Assets. Recomputed by
+     * `assetUsageAggregator` whenever `commitSynced` runs, mirroring the
+     * `secretIndex.entries[].usedIn` pattern. Local-only because it's pure
+     * cache — the truth lives in `synced.collections.requests` and
+     * `synced.mockServers`.
+     */
+    assetUsageIndex?: Record<string, AssetUsage>;
+    /**
+     * Slot ids whose attachment blob needs to be DELETED from the working
+     * branch on the next push. Queued by `removeGlobalFileAsset` (and the
+     * headless `globalAsset.removeFile` patch) when the asset being
+     * deleted had any push provenance (`workingBranchRef` or
+     * `baseBranchRef`). The push emits
+     * `{path: '.apicircle/workspace-<id>/attachments/<slotId>', sha: null}`
+     * tree entries layered over `base_tree`, which GitHub treats as
+     * deletions. After a successful push, the queue is cleared — the
+     * deletion is durable on the working branch, and the eventual PR
+     * merge propagates it to the base branch.
+     *
+     * Without this queue, the asset would be removed from `workspace.json`
+     * but the orphan blob would persist on the remote tree forever.
+     */
+    pendingAttachmentDeletes?: string[];
 }
 interface WorkspaceLocalSettings {
     validateOnSend: boolean;
@@ -1283,7 +1420,7 @@ declare const REQUEST_AUTH_TYPES: ReadonlyArray<RequestAuthType>;
  * clients can group them in their UI. Keep in sync with the registry in
  * `packages/mcp-server/src/tools/registry.ts`.
  */
-type McpToolName = 'import.curl' | 'import.openapi' | 'import.postman' | 'import.insomnia' | 'import.har' | 'generate.code' | 'workspace.list' | 'workspace.read' | 'workspace.write' | 'request.create' | 'request.read' | 'request.update' | 'request.delete' | 'folder.create' | 'folder.read' | 'folder.update' | 'folder.delete' | 'folder.export_json' | 'folder.import_json' | 'environment.create' | 'environment.read' | 'environment.update' | 'environment.delete' | 'environment.set_active' | 'environment.set_priority' | 'environment.export' | 'environment.import' | 'plan.create' | 'plan.run' | 'plan.read' | 'plan.update' | 'plan.delete' | 'plan.add_step' | 'plan.remove_step' | 'plan.reorder_steps' | 'plan.set_variables' | 'assertion.create' | 'assertion.read' | 'assertion.update' | 'assertion.delete' | 'history.list_runs' | 'history.get_run' | 'history.delete_run' | 'history.purge_by_age' | 'codebase.extract_collection' | 'prompt.create_environment' | 'prompt.create_assertion' | 'prompt.create_plan' | 'prompt.create_request' | 'prompt.update_request' | 'prompt.create_folder_tree' | 'prompt.add_plan_steps' | 'prompt.set_plan_variables' | 'prompt.create_mock_server' | 'prompt.add_mock_endpoint' | 'prompt.set_endpoint_validation_rules' | 'prompt.set_endpoint_response_rules' | 'prompt.set_endpoint_multipliers' | 'mock.create_from_openapi' | 'mock.create_from_postman' | 'mock.create_from_insomnia' | 'mock.create_manual' | 'mock.list' | 'mock.list_endpoints' | 'mock.start' | 'mock.stop' | 'mock.delete' | 'mock.add_endpoint' | 'mock.update_endpoint' | 'mock.delete_endpoint' | 'mock.set_validation_rules' | 'mock.set_response_rules' | 'mock.set_multipliers' | 'mock.import_postman_mock_collection';
+type McpToolName = 'import.curl' | 'import.openapi' | 'import.postman' | 'import.insomnia' | 'import.har' | 'generate.code' | 'workspace.list' | 'workspace.read' | 'workspace.write' | 'request.create' | 'request.read' | 'request.update' | 'request.delete' | 'folder.create' | 'folder.read' | 'folder.update' | 'folder.delete' | 'folder.export_json' | 'folder.import_json' | 'environment.create' | 'environment.read' | 'environment.update' | 'environment.delete' | 'environment.set_active' | 'environment.set_priority' | 'environment.export' | 'environment.import' | 'plan.create' | 'plan.run' | 'plan.read' | 'plan.update' | 'plan.delete' | 'plan.add_step' | 'plan.remove_step' | 'plan.reorder_steps' | 'plan.set_variables' | 'assertion.create' | 'assertion.read' | 'assertion.update' | 'assertion.delete' | 'history.list_runs' | 'history.get_run' | 'history.delete_run' | 'history.purge_by_age' | 'codebase.extract_collection' | 'prompt.create_environment' | 'prompt.create_assertion' | 'prompt.create_plan' | 'prompt.create_request' | 'prompt.update_request' | 'prompt.create_folder_tree' | 'prompt.add_plan_steps' | 'prompt.set_plan_variables' | 'prompt.create_mock_server' | 'prompt.add_mock_endpoint' | 'prompt.set_endpoint_validation_rules' | 'prompt.set_endpoint_response_rules' | 'prompt.set_endpoint_multipliers' | 'prompt.set_endpoint_request_schema' | 'assets.list_files' | 'assets.create_file' | 'assets.update_file' | 'assets.delete_file' | 'mock.create_from_openapi' | 'mock.create_from_postman' | 'mock.create_from_insomnia' | 'mock.create_manual' | 'mock.list' | 'mock.list_endpoints' | 'mock.start' | 'mock.stop' | 'mock.delete' | 'mock.add_endpoint' | 'mock.update_endpoint' | 'mock.delete_endpoint' | 'mock.set_validation_rules' | 'mock.set_response_rules' | 'mock.set_multipliers' | 'mock.set_request_schema' | 'mock.set_default_port' | 'mock.import_postman_mock_collection' | 'release.list' | 'release.publish' | 'release.deprecate' | 'release.yank' | 'linked.list' | 'linked.get' | 'linked.set_config' | 'linked.unlink' | 'linked.link' | 'linked.refresh' | 'release.tag' | 'repo.set_topics' | 'marketplace.search';
 interface McpError {
     code: 'invalid_input' | 'not_found' | 'conflict' | 'unsupported' | 'internal';
     message: string;
@@ -1292,4 +1429,4 @@ interface McpError {
 /** Helper: full enumeration of tool names — useful for the docs / config UIs. */
 declare const MCP_TOOL_NAMES: ReadonlyArray<McpToolName>;
 
-export { type Assertion, type AttachmentRef, type AwsSigV4Auth, type BodyType, type ConnectedRepo, type ContextExtraction, DEFAULT_WORKSPACE_NAME, type DigestAuth, type EnvPriorityRef, type Environment, type EnvironmentVariable, type EnvironmentVariableOverride, type ExecutionPlan, FONT_SIZE_PERCENT_DEFAULT, FONT_SIZE_PERCENT_MAX, FONT_SIZE_PERCENT_MIN, FONT_SIZE_PERCENT_STEP, type Folder, type FolderNode, type FontFamilyId, type FormDataRow, type GitHubSession, type GlobalFileAsset, type GlobalGraphQL, type GlobalSchema, type HawkAuth, type HttpMethod, type JwtBearerAuth, type LinkedSnapshot, type LinkedWorkspace, type LocalAttachmentCacheEntry, MCP_TOOL_NAMES, type McpError, type McpToolName, type MockConditionClause, type MockConditionOp, type MockConditionScope, type MockEndpoint, type MockMultiplierSource, type MockMultiplierSourceKind, type MockParamDef, type MockRequestSchema, type MockResponseBody, type MockResponseBodyType, type MockResponseConfig, type MockResponseMultiplier, type MockResponseRule, type MockRuntime, type MockRuntimeEntry, type MockServer, type MockServerSource, type MockValidationKind, type MockValidationRule, type NtlmAuth, type OAuth2AuthCodeAuth, type OAuth2ClientCredentialsAuth, type OAuth2DeviceAuth, type OAuth2ImplicitAuth, type OAuth2PasswordAuth, type OAuth2PkceAuth, type OAuth2TokenState, type PanelId, type PlanRun, REQUEST_AUTH_TYPES, RUN_BODY_PREVIEW_LIMIT, type ReleaseHistory, type ReleaseVersion, type Request, type RequestAuth, type RequestAuthType, type RequestBody, type RequestOverride, type RequestOverridePatch, type RequestRun, type RetiredBranch, type SecretCryptoMeta, type SecretEntry, type SecretIndex, type SecretKeyMeta, type SecretUsage, type SyncSnapshot, type ThemeId, type ValidationResult, type WorkingBranch, type WorkspaceLocal, type WorkspaceSnapshot, type WorkspaceSnapshotLedger, type WorkspaceSnapshotTrigger, type WorkspaceSynced, coerceMockResponseBodyTypeForStatus, defaultAuthFor, envPriorityDisplayName, envPriorityKey, envPriorityRefEqual, formatBytes, generateId, getAllowedMockResponseBodyTypes, makeDefaultMockResponse, makeDefaultMockResponseBody, makeDefaultRequestSchema, normalizeAuth, parseEnvPriorityKey, safeExternalHref, utf8ByteLength, validateAwsRegion, validateEnvVarName, validateHttpHeaderName, validateJsonPath, validateJsonString, validateMockPath, validatePRTitle, validatePlanName, validatePositiveDuration, validateRegex, validateUrl };
+export { type Assertion, type AssetGitRef, type AssetUsage, type AttachmentRef, type AwsSigV4Auth, type BodyType, type ConnectedRepo, type ContextExtraction, DEFAULT_WORKSPACE_NAME, type DigestAuth, type EnvPriorityRef, type Environment, type EnvironmentVariable, type EnvironmentVariableOverride, type ExecutionPlan, FONT_SIZE_PERCENT_DEFAULT, FONT_SIZE_PERCENT_MAX, FONT_SIZE_PERCENT_MIN, FONT_SIZE_PERCENT_STEP, type Folder, type FolderNode, type FontFamilyId, type FormDataRow, type GitHubSession, type GlobalFileAsset, type GlobalGraphQL, type GlobalSchema, type HawkAuth, type HttpMethod, type JwtBearerAuth, type LinkedSnapshot, type LinkedWorkspace, type LocalAttachmentCacheEntry, MAX_RESPONSE_MULTIPLIERS, MAX_RESPONSE_RULE_CONDITIONS, MCP_TOOL_NAMES, type McpError, type McpToolName, type MockConditionClause, type MockConditionOp, type MockConditionScope, type MockEndpoint, type MockMultiplierSource, type MockMultiplierSourceKind, type MockParamDef, type MockRequestSchema, type MockResponseBody, type MockResponseBodyType, type MockResponseConfig, type MockResponseMultiplier, type MockResponseRule, type MockRuntime, type MockRuntimeEntry, type MockServer, type MockServerSource, type MockValidationKind, type MockValidationRule, type NtlmAuth, type OAuth2AuthCodeAuth, type OAuth2ClientCredentialsAuth, type OAuth2DeviceAuth, type OAuth2ImplicitAuth, type OAuth2PasswordAuth, type OAuth2PkceAuth, type OAuth2TokenState, type PanelId, type PendingFileUpload, type PlanRun, REQUEST_AUTH_TYPES, RUN_BODY_PREVIEW_LIMIT, type ReleaseHistory, type ReleaseVersion, type Request, type RequestAuth, type RequestAuthType, type RequestBody, type RequestOverride, type RequestOverridePatch, type RequestRun, type RetiredBranch, type SecretCryptoMeta, type SecretEntry, type SecretIndex, type SecretKeyMeta, type SecretUsage, type SyncSnapshot, type ThemeId, type ValidationResult, type WorkingBranch, type WorkspaceLocal, type WorkspaceSnapshot, type WorkspaceSnapshotLedger, type WorkspaceSnapshotTrigger, type WorkspaceSynced, coerceMockResponseBodyTypeForStatus, defaultAuthFor, envPriorityDisplayName, envPriorityKey, envPriorityRefEqual, formatBytes, generateId, getAllowedMockResponseBodyTypes, makeDefaultMockResponse, makeDefaultMockResponseBody, makeDefaultRequestSchema, normalizeAuth, parseEnvPriorityKey, safeExternalHref, utf8ByteLength, validateAwsRegion, validateEnvVarName, validateHttpHeaderName, validateJsonPath, validateJsonString, validateMockPath, validatePRTitle, validatePlanName, validatePositiveDuration, validateRegex, validateUrl };

package/dist/index.js

@@ -396,6 +396,11 @@ var MCP_TOOL_NAMES = [
   "prompt.set_endpoint_validation_rules",
   "prompt.set_endpoint_response_rules",
   "prompt.set_endpoint_multipliers",
+  "prompt.set_endpoint_request_schema",
+  "assets.list_files",
+  "assets.create_file",
+  "assets.update_file",
+  "assets.delete_file",
   "mock.create_from_openapi",
   "mock.create_from_postman",
   "mock.create_from_insomnia",
@@ -411,10 +416,27 @@ var MCP_TOOL_NAMES = [
   "mock.set_validation_rules",
   "mock.set_response_rules",
   "mock.set_multipliers",
-  "mock.import_postman_mock_collection"
+  "mock.set_request_schema",
+  "mock.set_default_port",
+  "mock.import_postman_mock_collection",
+  "release.list",
+  "release.publish",
+  "release.deprecate",
+  "release.yank",
+  "linked.list",
+  "linked.get",
+  "linked.set_config",
+  "linked.unlink",
+  "linked.link",
+  "linked.refresh",
+  "release.tag",
+  "repo.set_topics",
+  "marketplace.search"
 ];
 
 // src/mock.ts
+var MAX_RESPONSE_MULTIPLIERS = 1;
+var MAX_RESPONSE_RULE_CONDITIONS = 1;
 var NO_BODY_STATUSES = /* @__PURE__ */ new Set([100, 101, 102, 103, 204, 205, 304]);
 function getAllowedMockResponseBodyTypes(status) {
   if (NO_BODY_STATUSES.has(status)) return ["none"];
@@ -457,6 +479,8 @@ export {
   FONT_SIZE_PERCENT_MAX,
   FONT_SIZE_PERCENT_MIN,
   FONT_SIZE_PERCENT_STEP,
+  MAX_RESPONSE_MULTIPLIERS,
+  MAX_RESPONSE_RULE_CONDITIONS,
   MCP_TOOL_NAMES,
   REQUEST_AUTH_TYPES,
   RUN_BODY_PREVIEW_LIMIT,