Sasha MCP reference

deleteAppFile

Delete one source file of a Sasha App you manage

Delete a package file (never APP.md). Pass the version from readAppFile. Remove any reference to the file first (an APP.md action declaration, a <link> or <script> in index.html) or the app stops validating. LIVE immediately, no undo. If this call returns an error, the change may still have landed. Call readAppFile before retrying. The result carries status: when status.ok is false the app is NOT usable until the listed diagnostics are fixed. Each names the package file, the line when known, the error code and a reason token. Fix the file and check again; the app is live as soon as it validates.

Arguments

Scopes

apps:invoke, apps:write

Annotations

• Read only: no
• Destructive: yes

When to use

Use deleteAppFile to remove a file that the app no longer needs.

The tool needs the same access as listAppFiles: the scopes apps:invoke and apps:write, an admin or staff user, and manage access on the app. There is no confirmation step for the source tools.

1. Remove every reference to the file first, with editAppFile. For example, an action declaration in APP.md, or a <link> or <script> element in index.html. If a reference stays, the app stops validating.
2. Call readAppFile for the file, and keep its version.
3. Call deleteAppFile with that version as expectedVersion and a one-line reason (1 to 100 characters, recorded in the audit log).

Rules:

• APP.md can never be deleted.
• expectedVersion is required. The delete is refused if the file changed after your read.
• The delete is live at once. There is no undo. To get the file back, you must write it again with writeAppFile.

The result has deleted: true and status. When status.ok is false, something still needs the file, or the package has another problem. Read status.diagnostics, fix the named file, and call checkApp.

If the call returns an error, the delete can still have happened. Call listAppFiles or readAppFile before you retry.

Example

{
  "app": "timesheet",
  "path": "print.css",
  "reason": "Print styles moved into styles.css",
  "expectedVersion": "189f40034be7a199f1fa9891668ee3ab6049f82d38c68be70f596eab2e1857b7"
}

The structured result (structuredContent):

{
  "app": "timesheet",
  "path": "print.css",
  "deleted": true,
  "status": {
    "ok": true,
    "revision": "8254c329a92850f6d539dd376f4816ee2764517da5e0235514af433164480d7a",
    "diagnostics": []
  }
}

The text part of the result says Deleted print.css. and whether the app validates.

Refusals and what to do

The error result's text is the message. structuredContent.error holds code, message, retryable and diagnosticId.

• APP_SOURCE_FILE_INVALID: the path is APP.md, or the file type is not one that these tools handle. APP.md cannot be deleted.
• APP_SOURCE_CONFLICT: the file changed after you read it. Call readAppFile again and decide whether the file should still be deleted.
• APP_NOT_FOUND (app_not_found): there is no file at that path. It can be deleted already. Check with listAppFiles.
• APP_INPUT_INVALID (app_input_invalid): the arguments do not match the schema. Examples: a missing expectedVersion, an expectedVersion that is not 64 hex characters, or a reason that is empty, longer than 100 characters or has a control character.
• APP_PATH_INVALID (app_path_invalid): the path is not a valid package path. Use a path from listAppFiles.
• APP_ACCESS_DENIED (app_access_denied): this person does not have manage access on the app, or is not an admin or staff user. An app id that does not exist gets the same answer.
• If the connection does not hold both apps:invoke and apps:write, the tool is not in your tool list, and a call to it returns MCP error -32602: Tool deleteAppFile not found. Read the permissions section of getDocs. The person must reconnect, or mint a new token, with apps:write. Only admin and staff can hold it.

Related

• editAppFile removes the references to the file first.
• readAppFile gives the version.
• writeAppFile creates a file again.
• listAppFiles and checkApp show the package status.