Just noticed this thread, and yes I have some ideas 
To get a general feel what an Applescript Suite should support, run the Script Editor and open the dictionary for DevonThink. You’ll notice two types of exports: data types (i.e. objects with properties) and actions (routines called to get objects or interact with the app).
If I were adding Applescript for Scrivener, I’d add at least the following data types:
Application (has Active Wndow contains DocumentWindow, Current Project, Recent Projects, etc)
DocumentWindow (has Selected Text and such)
Project (has name, notes, contains Binder)
Binder (contains BinderItems, has Root Group which contains Drafts/Trash/etc)
BinderItem (has name, path, synopsis, notes, references, type, label, status, keywords, etc)
…and so forth.
I’d support the following actions like the following:
open project (closes current project)
create binder item at path
delete (to trash) binder item at path
move binder item at path to path
get binder item at path
take snapshot
backup project to file_path
export project to file_path
import file at file_path to path
Applescript is used for two things: automation and interacting with other applications (could be considered the same thing actually).
This means that there needs to be direct access to the raw data in Scrivener (text, keywords, labels, status, references, and notes) via data types, and access to commonly-automated tasks (opening, saving, exporting, importing) via actions.
In an application like Scrivener, exposing the data types (which are all native to OS X and will play well with Applescript) is more important that providing routines. Consider the likely use cases, and how the scripts for them would be written:
- List unfinished items: iterate over documents, printing all with TODO status. Same applies for listing document keywords, references, etc.
- Add metadata to a document: find document, modify notes/ref/keyword/status/synopsis
- Apply text changes: find document, modify RTF directly
- Add file to project: invoke import routine
- Export data from project: compile export settings and list of object IDs to export, then invoke export routine
- Send selected text to application : get selected text, tell application
I don’t see much value in adding applescript support for the kind of stuff that generally requires human interaction/judgement, e.g. merging and splitting documents/empty trash, or for the stuff that applescripts can easily do themselves, e.g. convert case/insert date/etc.
So the heart of the applescript suite would be the BinderItem data type:
BinderItem
Name (string)
Location (string: path from Binder root)
Path (string: path inside project dir)
Type (r/o)
Title (string)
Label (integer)
Status (integer)
Synopsis (string)
Create Date (r/o)
Mod Date (r/o)
Include in Export (boolean)
Page Break Before (boolean)
Preserve Formatting (boolean)
Notes (string)
Keywords (list of Keyword objects)
References (list of Reference objects)
Target (?)
Progress (?)
Children (list of BinderItem objects)
Note word count and char count are unneccessary for BinderItem as they are inherent properties of applescript strings, though per-project counts should be included.
Based on this, the rest of the data types become obvious (Reference, Keyword, Binder containing BinderItems, Window containing Binder, Application containing Window), and the routines simply become ways to either to access (create/find/delete) the types, or to perform operations that aren’t related to modifying data stored in types.
