Editing the source of a Sasha App
This is the apps-authoring section of the usage guide. Call getDocs with { "section": "apps-authoring" } to read it on an instance.
Available only when listAppFiles, readAppFile, writeAppFile, editAppFile,
deleteAppFile and checkApp are in your tool list: the apps:write scope, an
admin or staff user, and manage access on the app. They edit the LIVE package
under the apps root. There is no draft, no preview and no undo. A change is live
the moment the package validates.
The loop:
listAppFilesto see the package and itsstatus;readAppFilethe files you will change (APP.md first: it declares tables, actions and the entry file).editAppFilefor a passage,writeAppFileto create or replace a whole file,deleteAppFileto remove one. Every mutation takes theversionyou last read asexpectedVersion(omit it only to CREATE). A stale version is refused.- Read the returned
status. Whenstatus.okis false the app is not usable until every diagnostic is fixed: each names the package file, the line when known, the error code and a reason token (for exampleAPP.md:4 APP_MANIFEST_INVALID unknown_field:bogus). Fix the file, thencheckApp. Whenstatus.okis true the app is live atstatus.revision.
Schema changes: never edit a migration that this instance has already applied.
The diagnostics say migration_already_applied_here. Add a new
migrations/NNN-*.sql and change schema.sql so replaying all migrations
matches it exactly. Allowed files: .md .html .css .js .sql .yaml .yml .json .txt
.svg, 1 MiB each, 64 files per package. Once a bundled app is edited here it is
yours: the next upgrade preserves it and no longer refreshes it.
Before changing an app, read the app-builder skill in the knowledge base for
the package contract (APP.md fields, the window.Sasha façade, App Actions).