Scripts and projects

A .js file is enough for a small task. A .cso or .aso project is an ordinary directory containing related scripts and assets. Both extensions are supported. A project starts main.js, or index.js if main.js is absent.

Create a project in the app

Choose Scripts → + → Create project (.aso). The dialog accepts .cso too. Open the project to edit its entry and add folders or files. Run from a file inside a project saves its drafts and starts the project entry. Save writes only the current file.

Scripts live under the device’s resolved ApplesauceOS Scripts folder. Use scriptsDir() to find it; do not hard-code a jailbreak prefix. Import from Files accepts scripts and folders. Long-press a library item for actions such as rename, duplicate, share and delete.

Let modules call other modules

Greeting.cso/
  main.js
  actions/
    greeting.js
    format.js
  config.json

main.js:

const {greet} = require("./actions/greeting");
greet(args.name || "Sam");

actions/greeting.js:

const {format} = require("./format");
const config = require("../config.json");
exports.greet = function (name) {
  console.log(format(config.prefix, name));
};

actions/format.js:

exports.format = (prefix, name) => prefix + ", " + name + "!";

config.json:

{"prefix":"Hello"}

Every ./ path belongs to the file doing the import. ../ moves to its parent. Loading a module does not start a separate script; exported functions run when you call them. Modules are cached within each iteration and receive a fresh cache on the next run.

Files and assets

Use __dirname + "/result.json" for data beside the current module. Native file functions do not use CommonJS resolution. Check their documented result: writeFile returns null on success and an error string on failure.

findImage resolves a relative template path from the script/project directory. Keep assets in the project so it can move between devices. An image in Photos is not automatically a template file in your project.

Arguments

Arguments arrive in the reserved, frozen args object, also available as at.args. Values are strings. A missing key is undefined.

const count = Number(args.count || "3");
if (!Number.isInteger(count) || count < 1 || count > 10) {
  throw new Error("count must be an integer from 1 to 10");
}

The MCP start_script tool accepts path and args. Keep the returned run ID to inspect or stop that run. Do not use a shared temporary file for arguments.

JavaScript packages

The loader supports CommonJS .js/.cjs, JSON, directory indexes, package.json.main for imported modules, and nested node_modules. It does not automatically install npm packages. Pure JavaScript packages can work if their dependencies use available APIs.

This is not Node.js: built-ins such as fs, http, net, child_process, process, Buffer, native addons and package exports maps are not provided. ES modules must be bundled to CommonJS. Use file APIs, HTTP APIs and execResult where appropriate.

Next: JavaScript conventions and reliable automation.