Ok, so forgive me if any of this is teaching you to suck eggs!
In the early days of UXP there was no arbitrary file acces and the token system was the only method of accessing files. The intention was to disallow plugins from gaining access to the filesystem without user consent. There is now the ability for arbitrary access but let’s ignore that for now.
A token is essentially a key/value pair of a path and a unique ID that PS holds in memory that says “User has granted permission to access this file/folder”. There are two types of token - Session, which is temporary and lasts for the duration of that PS session, and Persistent, which will be available in all PS sessions in the future. To use a persistent token in the future you’re going to need to save it somewhere (a JSON file, a database, etc) so you can access it - you can’t “get” it from PS later.
In the case of a folder, a token also provides access to any descendents.
A new, unsaved document doesn’t have a token/entry as it purely exists in memory until it is saved.
The only way to generate a token is via a file picker using one of the File System Provider methods.
How you handle that depends on your use case, desired UX, and general preference.
One approach would be to use a file picker every time you need to create a token, another would be to have users grant access to a dedicated working folder once using a persistent token (for example in a settings page/dialog) and then all your code is targeted to that folder.
Once we have a token we can use it to get an entry with the relevant getEntryFor...Token method (see previous link) that then allows us to interact with the file using the various entry methods, although not always - e.g. saveAs is passed a token and not an entry.
In a nutshell , we don’t really interact with the file itself much, we create a token and then interact with the entry.
So, to consider your use case:
I’m going to make two assumptions - 1) The master file is new and has never been saved 2) the smart object will be created programmatically and as such will not have been saved either.
The user reaches the point where they have opened and edited the smart object and via some undetermined mechanism indicates that they are ready to save and close the smart object - at this point your code is going to do something like this:
• Generate token via user input/file picker (for a folder to save in)
• With token, get entry for folder
• Create a file entry within folder
• Create token for file
• Write smart object to file with token
• Close smart object
As you now have a token/entry for a folder any subsequent operations can use it (more smart objects, saving the master file, etc).
That’s a super reductive summary and there’s definitely more to consider, especially as you want to cede control to user which can get messy very quickly (what if they create and open a new smart object within the smart object for example).
Here’s a repo I made to demonstrate using a single persistent token to grant permanent access to a working folder. It might be a bit overwhelming, but it contains a lot of the ingredients for what you want, tokens, saving, and batchPlay. It also demonstrates the more functional approach to coding mentioned before.