@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/groups.mjs

@@ -0,0 +1,417 @@
+/**
+ * Substrio CLI: command groups, each subcommand a registry operation run through
+ * `substrio op` (runOperation). This table is the CLI's only map from words to
+ * operations: routes, methods and input schemas come from the server's
+ * catalog (GET /v1/_openapi), and help and usage are generated from here.
+ * Bare words fill the route's path parameters in order; key=value, --data,
+ * --file and --raw work as in `substrio op`.
+ *
+ * PURE: data only, nothing that touches the network, crypto or the file
+ * system. `command-table.mjs` imports this module unconditionally (it builds
+ * `substrio --help`/`substrio --version` before any command runs), so it stays this
+ * light; a group's actual run (a server call, a file write) is
+ * `./groups-runtime.mjs`, loaded only when a group command runs.
+ *
+ * An entry is an operation name, or { operation, trailing, method, defaults }:
+ *   trailing  the last bare words become these input fields (after the
+ *             route's path parameters); a value of "-" is read from stdin
+ *   method    which of the operation's routes (secret.write: PUT or POST)
+ *   defaults  input fields used when the caller gives none
+ *   text      trailing values stay text (else JSON when they parse, as key=value)
+ *   render    prints a successful result as text (JSON under --json or --raw)
+ *   body      the input field that is the operation's whole body (data insert:
+ *             "document"): --data, --file and key=value make that value, so
+ *             --data is the document itself, with no wrapper
+ *   flow      a command of its own for the words (GroupFlow), not one call
+ *   note      what help says of the words in place of the operation's name
+ *   valueFlags  the flags of a flow that take a value, so their value is not a bare word
+ *   destructive  computed (entryOf), not given: the words destroy data or
+ *                cannot be undone, from the operation's own trailing word
+ *                (or the sub-command's, for one whose operation name differs,
+ *                such as domains remove naming tenant.domain.detach)
+ *
+ * Every registry group (the first word of an operation's name) belongs to
+ * one command (REGISTRY_GROUPS): `substrio COMMAND WORD ...` runs GROUP.WORD...
+ * (the longest such name the server has; hyphens read as underscores) when
+ * WORD is not one of the command's own, so no operation is left without a
+ * command. Groups with no words of their own have an empty table here.
+ *
+ * No key or token is ever printed, except the invite link `invite` returns:
+ * `accounts keys create` writes the new key to --out FILE (owner-only).
+ */
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', red: '\x1b[91m', dim: '\x1b[2m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+// One sandbox: its name, slug, the version it runs and its addresses.
+function showSandbox(s) {
+    console.log(`  ${C.bold}${s.name}${C.reset} ${C.dim}(${s.slug})${C.reset} ` +
+        `${s.live ? `runs version ${s.live}` : `${C.dim}runs no version yet${C.reset}`}`);
+    for (const host of s.hosts || []) console.log(`    ${C.cyan}${host}${C.reset}`);
+}
+
+// The declared permission catalog (permissions.get's shape): one row per
+// name, its bit and the names its closure implies (itself excluded); the all
+// name, if one closes to every bit, named last. docs/permissions.md.
+function showPermissionCatalog({ names = [], all = null }) {
+    if (!names.length) {
+        console.log(`${C.dim}No permissions declared. substrio deploy sets them from substrio.toml's [permissions] table.${C.reset}`);
+        return;
+    }
+    console.log(`\n${C.bold}Permissions (${names.length})${C.reset}\n`);
+    for (const n of names) {
+        console.log(`  ${C.bold}${n.name}${C.reset} ${C.dim}bit ${n.bit}${n.implies.length ? `, implies ${n.implies.join(', ')}` : ''}${C.reset}`);
+    }
+    console.log(all ? `\n${C.dim}all: ${all}${C.reset}\n` : '');
+}
+
+// One user's permissions (user.permissions.get/set's shape): granted (the
+// stored raw names) and effective (granted, closed over implies).
+function showUserPermissions({ granted = [], effective = [] }) {
+    console.log(`${C.bold}Granted:${C.reset} ${granted.length ? granted.join(', ') : `${C.dim}none${C.reset}`}`);
+    console.log(`${C.bold}Effective:${C.reset} ${effective.length ? effective.join(', ') : `${C.dim}none${C.reset}`}`);
+}
+
+// One user's memberships (user.memberships.get's shape): the one
+// organization's names (collection and id given, {names}), or every
+// organization held (user_id alone, {memberships: [{organization, names}]}).
+function showUserMemberships(data) {
+    if (Array.isArray(data.memberships)) {
+        if (!data.memberships.length) {
+            console.log(`${C.dim}No memberships held.${C.reset}`);
+            return;
+        }
+        for (const { organization, names = [] } of data.memberships) {
+            console.log(`${C.bold}${organization}${C.reset}: ${names.length ? names.join(', ') : `${C.dim}none${C.reset}`}`);
+        }
+        return;
+    }
+    const names = data.names || [];
+    console.log(`${C.bold}Names:${C.reset} ${names.length ? names.join(', ') : `${C.dim}none${C.reset}`}`);
+}
+
+const SANDBOX = { defaults: { name: 'dev' } };
+// create and reset answer {sandbox}: shown as text.
+const SANDBOX_SHOWN = { ...SANDBOX, render: (data) => showSandbox(data.sandbox) };
+
+function showSandboxes({ sandboxes = [] }) {
+    if (!sandboxes.length) {
+        console.log(`${C.dim}No sandboxes. substrio push makes dev; substrio sandbox create NAME makes another.${C.reset}`);
+        return;
+    }
+    console.log(`\n${C.bold}Sandboxes (${sandboxes.length})${C.reset}\n`);
+    for (const s of sandboxes) showSandbox(s);
+    console.log('');
+}
+
+/** The group words that run a flow of their own, not one operation call. */
+export const GroupFlow = Object.freeze({
+    IMPORT: 'import',               // data import: a file of documents, in batches (commands/import.mjs)
+    COUNT: 'count',                 // data count: query.count, or data.query with count when a where filter is given (commands/count.mjs)
+    MCP_CONFIG: 'mcp-config',       // mcp config: the MCP client config of the profile's app (commands/mcp-config.mjs)
+    TOOL_INSTALL: 'tool-install',   // tools install: hash the file once, stream it once as the PUT body (commands/tools.mjs)
+    SECRET_SET: 'secret-set',       // secrets set: the value from stdin, --from-file or --from-env, never a bare word (groups-runtime.mjs)
+    USER_PERMISSIONS_GRANT: 'user-permissions-grant',   // permissions grant USER_ID NAME ...: a variable number of trailing names, not one fixed field (groups-runtime.mjs)
+    USER_PERMISSIONS_REVOKE: 'user-permissions-revoke', // permissions revoke USER_ID NAME ...: likewise (groups-runtime.mjs)
+    USER_MEMBERSHIPS_GRANT: 'user-memberships-grant',   // memberships grant USER_ID NAME ... --in COLLECTION:ID: likewise, plus --in (groups-runtime.mjs)
+    USER_MEMBERSHIPS_REVOKE: 'user-memberships-revoke', // memberships revoke USER_ID NAME ... --in COLLECTION:ID: likewise (groups-runtime.mjs)
+    USER_MEMBERSHIPS_SHOW: 'user-memberships-show',     // memberships show USER_ID [--in COLLECTION:ID]: user.memberships.get is a GET, its fields travel in the query string (groups-runtime.mjs)
+});
+
+// command -> subcommand -> operation. The first subcommand is the default;
+// aliases share an operation. A two-word subcommand ("keys create") wins
+// over its first word alone.
+export const GROUPS = {
+    data: {
+        list: 'data.list', get: 'data.get',
+        insert: {
+            operation: 'data.insert', body: 'document',
+            note: `data.insert: --data '{...}' (or --file F, or key=value) is the document itself, no wrapper`,
+        },
+        update: 'data.update',
+        delete: 'data.delete', rm: 'data.delete', query: 'data.query',
+        count: {
+            operation: 'query.count', flow: GroupFlow.COUNT,
+            note: 'query.count: where.FIELD=VALUE (or --data \'{"where":{...}}\') filters it as in data query',
+        },
+        aggregate: 'query.aggregate',
+        import: {
+            operation: 'data.import', flow: GroupFlow.IMPORT,
+            valueFlags: ['--format', '--types', '--empty-as', '--batch-bytes', '--batch-docs', '--concurrency', '--checkpoint', '--on-conflict'],
+            note: 'data.import: --file F (NDJSON .ndjson/.jsonl, a JSON array, {"documents":[...]} or --format csv; - is stdin), streamed and sent in batches (--batch-bytes, --batch-docs, --concurrency); --checkpoint and --resume survive a crash; each rejected document is reported',
+        },
+        export: 'data.export',
+    },
+    collections: {
+        list: 'collection.list', create: { operation: 'collection.create', trailing: ['name'] },
+        delete: 'collection.delete', rm: 'collection.delete', stats: 'collection.stats', schema: 'schema.get',
+    },
+    functions: {
+        list: 'function.list', get: 'function.get', invoke: 'function.invoke', delete: 'function.delete',
+        rm: 'function.delete', toggle: 'function.toggle', source: 'function.source.read', logs: 'function.logs',
+    },
+    secrets: {
+        list: 'secret.list',
+        set: {
+            flow: GroupFlow.SECRET_SET, valueFlags: ['--from-file', '--from-env'],
+            note: 'secrets set KEY: the value from stdin (or -), --from-file PATH, or --from-env NAME; never a plain argument',
+        },
+        delete: { operation: 'secret.delete', trailing: ['key'] },
+        rm: { operation: 'secret.delete', trailing: ['key'] },
+    },
+    cron: {
+        list: 'schedule.list', create: 'schedule.create', update: 'schedule.update',
+        enable: { operation: 'schedule.update', defaults: { enabled: true } },
+        disable: { operation: 'schedule.update', defaults: { enabled: false } },
+        delete: 'schedule.delete', rm: 'schedule.delete',
+    },
+    triggers: {
+        list: 'trigger.list', create: 'trigger.create', update: 'trigger.update',
+        enable: { operation: 'trigger.update', defaults: { enabled: true } },
+        disable: { operation: 'trigger.update', defaults: { enabled: false } },
+        delete: 'trigger.delete', rm: 'trigger.delete',
+    },
+    domains: {
+        list: 'tenant.domain.list', add: { operation: 'tenant.domain.attach', trailing: ['domain'] },
+        remove: 'tenant.domain.detach', rm: 'tenant.domain.detach',
+    },
+    rules: { get: 'security.rules.get', set: 'security.rules.set', delete: 'security.rules.delete' },
+    permissions: {
+        get: { operation: 'permissions.get', render: showPermissionCatalog },
+        set: 'permissions.set',
+        grant: {
+            flow: GroupFlow.USER_PERMISSIONS_GRANT,
+            note: "permissions grant USER_ID NAME ...: grants that user those declared permissions (user.permissions.set); effective at their next sign in",
+        },
+        revoke: {
+            flow: GroupFlow.USER_PERMISSIONS_REVOKE,
+            note: "permissions revoke USER_ID NAME ...: revokes those declared permissions (user.permissions.set); ends the user's sessions now if any was actually held",
+        },
+        show: {
+            operation: 'user.permissions.get', render: showUserPermissions,
+            note: "permissions show USER_ID: that user's granted and effective declared permission names",
+        },
+    },
+    memberships: {
+        grant: {
+            flow: GroupFlow.USER_MEMBERSHIPS_GRANT, valueFlags: ['--in'],
+            note: 'memberships grant USER_ID NAME ... --in COLLECTION:ID: grants that user those declared permissions in the named organization (user.memberships.set); the gate reads it from the next request',
+        },
+        revoke: {
+            flow: GroupFlow.USER_MEMBERSHIPS_REVOKE, valueFlags: ['--in'],
+            note: 'memberships revoke USER_ID NAME ... --in COLLECTION:ID: revokes those declared permissions in the named organization (user.memberships.set); holds from the next request, no session is ended',
+        },
+        show: {
+            flow: GroupFlow.USER_MEMBERSHIPS_SHOW, valueFlags: ['--in'], render: showUserMemberships,
+            note: 'memberships show USER_ID [--in COLLECTION:ID]: that organization\'s held names, or every organization held when --in is omitted',
+        },
+    },
+    sandbox: {
+        list: { operation: 'sandbox.list', render: showSandboxes },
+        create: { operation: 'sandbox.create', trailing: ['name'], ...SANDBOX_SHOWN },
+        reset: { operation: 'sandbox.reset', ...SANDBOX_SHOWN },
+        delete: { operation: 'sandbox.delete', ...SANDBOX },
+        rm: { operation: 'sandbox.delete', ...SANDBOX },
+        outbox: { operation: 'sandbox.outbox', ...SANDBOX },
+        allow: { operation: 'sandbox.allow.list', ...SANDBOX },
+        'allow add': { operation: 'sandbox.allow.add', ...SANDBOX },
+        'allow remove': { operation: 'sandbox.allow.remove', ...SANDBOX },
+    },
+    webhooks: {
+        list: 'webhook.list', get: 'webhook.get', show: 'webhook.get', create: 'webhook.create',
+        update: 'webhook.update', delete: 'webhook.delete', rm: 'webhook.delete', logs: 'webhook.logs',
+    },
+    views: {
+        list: 'view.list', data: 'view.get', get: 'view.get', create: 'view.create',
+        update: 'view.update', delete: 'view.delete', rm: 'view.delete', refresh: 'view.refresh',
+    },
+    backups: {
+        list: 'backup.list', get: 'backup.get', show: 'backup.get', create: 'backup.create',
+        restore: 'backup.restore', delete: 'backup.delete', rm: 'backup.delete',
+    },
+    accounts: {
+        list: 'account.list', show: 'account.get', get: 'account.get',
+        members: 'account.member.list', keys: 'account.key.list', apps: 'account.app.list',
+        'keys list': 'account.key.list', 'keys create': 'account.key.create', 'keys revoke': 'account.key.revoke',
+        invite: 'account.invite.create', invites: 'account.invite.list', revoke: 'account.invite.revoke',
+        role: 'account.member.set', remove: 'account.member.remove',
+        'attach-app': { operation: 'account.app.attach', trailing: ['account_id'] },
+    },
+    platform: {
+        settings: 'platform.settings.get', 'settings get': 'platform.settings.get',
+        'settings set': { operation: 'platform.setting.set', trailing: ['value'] },
+    },
+    tools: {
+        list: 'tool.list',
+        remove: { operation: 'tool.remove', trailing: ['name', 'version'] },
+        install: {
+            flow: GroupFlow.TOOL_INSTALL,
+            note: "tools install NAME FILE|-: streams the file once to hash it (sha256) and once as the PUT body (- is stdin, buffered to an owner-only temp file first, removed after)",
+        },
+    },
+    ledger: {
+        catalog: 'ledger.catalog.get', declare: 'ledger.catalog.set',
+        post: 'ledger.post', balance: 'ledger.balance', entries: 'ledger.entries',
+        entry: { operation: 'ledger.entry.get', trailing: ['id'] },
+        clear: { operation: 'ledger.entry.clear', trailing: ['id'] },
+        void: { operation: 'ledger.entry.void', trailing: ['id'] },
+        reverse: { operation: 'ledger.entry.reverse', trailing: ['id'] },
+        'clear-due': 'ledger.clear_due', import: 'ledger.import',
+    },
+    // Registry groups run by their words alone (substrio kv get KEY: kv.get).
+    agent: {}, ai: {}, audit: {}, auth: {}, batch: {}, cluster: {}, documentation: {}, edge: {}, graph: {}, job: {}, kv: {},
+    // The app history: ref.* runs by its words (substrio ref log branch main).
+    // branch.*, tag.*, merge.* and version.* have commands of their own
+    // (commands/history.mjs, commands/versions.mjs), which run any operation
+    // of their group that those commands have no word for.
+    ref: {},
+    // The history tree worked on as a project (MCP-PLAIN-SHIP): substrio source tree main, source search main
+    // --pattern X, source edit and source move by their words.
+    source: {},
+    live_view: {}, log_alert: {}, log_drain: {},
+    // mcp.* runs by its words; config is the CLI's own word, for the client side of the same endpoint.
+    mcp: { config: { flow: GroupFlow.MCP_CONFIG, valueFlags: ['--client', '--name', '--env'], note: 'a ready MCP client config for this profile\'s app (--client claude|cursor|generic); the key as an environment variable reference' } },
+    // host.* and node_label.* (the operator's host manifest) run by their words; host remove and
+    // node_label delete are gated by their own trailing word, as every other.
+    host: {}, node_label: {},
+    // TEST-HOSTS: root_domain.* (the platform admin's roots) runs by its words: substrio root_domain add
+    // domain=onstax.com. env.host.* runs through the env command (commands/env.mjs), beside its pull and push.
+    root_domain: {},
+    // BILLING, FEATURED-APPS, MCP-MODULES, PLATFORM-UPGRADES: their operations run by their words: substrio billing
+    // cart create, substrio featured enable, substrio package add, substrio release list.
+    billing: {}, featured: {}, package: {}, release: {},
+    mesh: {}, meta: {}, namespace: {}, oauth: {}, object: {}, observability: {},
+    oidc: {}, plans: {}, queue: {}, rag: {}, rate_limit: {}, sql: {}, index: {},
+    realtime: {}, role: {}, route: {}, search: {}, settings: {}, sync: {}, system: {}, thread: {}, user: {},
+};
+
+// Registry group -> the command that runs its operations: a group above, a
+// flow (tenants, files, site, versions) or an operation alias (undo).
+export const REGISTRY_GROUPS = Object.freeze({
+    account: 'accounts', agent: 'agent', ai: 'ai', app: 'tenants', audit: 'audit', auth: 'auth', backup: 'backups', batch: 'batch',
+    cluster: 'cluster', collection: 'collections', data: 'data', documentation: 'documentation', edge: 'edge', file: 'files',
+    function: 'functions', graph: 'graph', host: 'host', index: 'index', job: 'job', kv: 'kv', ledger: 'ledger', live_view: 'live_view',
+    log_alert: 'log_alert', log_drain: 'log_drain', mcp: 'mcp', mesh: 'mesh', meta: 'meta', namespace: 'namespace', node_label: 'node_label', oauth: 'oauth',
+    root_domain: 'root_domain', env: 'env', apps: 'tenants', billing: 'billing', featured: 'featured', package: 'package',
+    release: 'release',
+    object: 'object', observability: 'observability', oidc: 'oidc', permissions: 'permissions', plans: 'plans', queue: 'queue',
+    platform: 'platform', query: 'data', rag: 'rag', rate_limit: 'rate_limit', realtime: 'realtime',
+    branch: 'branch', tag: 'tag', ref: 'ref', merge: 'merge',
+    role: 'role', route: 'route', sandbox: 'sandbox', schedule: 'cron', schema: 'collections',
+    search: 'search', secret: 'secrets', source: 'source', security: 'rules', settings: 'settings', site: 'site',
+    sql: 'sql', sync: 'sync', system: 'system', tenant: 'tenants', thread: 'thread', tool: 'tools', trigger: 'triggers', undo: 'undo',
+    user: 'user', version: 'versions', view: 'views', webhook: 'webhooks',
+});
+
+/** The registry groups `command` runs (pure). */
+export function registryGroupsOf(command) {
+    return Object.keys(REGISTRY_GROUPS).filter((group) => REGISTRY_GROUPS[group] === command);
+}
+
+// The other names people type for a group.
+export const GROUP_ALIASES = {
+    webhook: 'webhooks', view: 'views', backup: 'backups', account: 'accounts',
+    collection: 'collections', fn: 'functions', function: 'functions', secret: 'secrets',
+    trigger: 'triggers', domain: 'domains', rule: 'rules', permission: 'permissions', membership: 'memberships', sandboxes: 'sandbox', tool: 'tools',
+};
+
+/** The group a command name names, or null. */
+export function groupOf(command) {
+    if (Object.hasOwn(GROUPS, command)) return command;
+    return GROUP_ALIASES[command] ?? null;
+}
+
+// Trailing verbs that destroy data or cannot be undone (from the registry's
+// own operation names: delete, revoke, remove, drop, purge, reset, clear,
+// restore cover every SUBSTRIO_OP whose DESC says so, checked against the whole
+// registry, not maintained by hand per command).
+const DESTRUCTIVE_WORDS = new Set(['delete', 'rm', 'remove', 'revoke', 'drop', 'purge', 'reset', 'clear', 'restore']);
+const lastWord = (name) => name.split(/[ .]/).pop();
+
+/** Whether the registry operation `name` destroys data or cannot be undone (pure, by its own trailing word). */
+export function isDestructiveOperation(name) {
+    return DESTRUCTIVE_WORDS.has(lastWord(name));
+}
+
+/** An entry in its full form (pure); `sub` (the table key) decides `destructive` when the operation's own name does not say so (domains remove: tenant.domain.detach). */
+export function entryOf(entry, sub = null) {
+    const plain = { operation: null, trailing: [], method: null, defaults: {}, text: false, render: null, body: null, flow: null, note: null, valueFlags: [] };
+    const full = typeof entry === 'string' ? { ...plain, operation: entry } : { ...plain, ...entry };
+    const destructive = full.operation !== null && (isDestructiveOperation(full.operation) || (sub !== null && DESTRUCTIVE_WORDS.has(lastWord(sub))));
+    return { ...full, destructive };
+}
+
+const isWord = (arg) => typeof arg === 'string' && !arg.startsWith('-') && !arg.includes('=');
+
+/**
+ * The operation the leading words of `args` name in `groups`, the longest
+ * name in `names` (a Set), and the arguments after those words; null when
+ * none (pure).
+ */
+export function registryOperation(names, groups, args) {
+    let count = 0;
+    while (count < args.length && isWord(args[count])) count++;
+    const words = args.slice(0, count).map((w) => w.replace(/-/g, '_'));
+    for (let used = count; used >= 0; used--) {
+        for (const group of groups) {
+            const name = [group, ...words.slice(0, used)].join('.');
+            if (names.has(name)) return { operation: name, rest: args.slice(used) };
+        }
+    }
+    return null;
+}
+
+/**
+ * The operation and arguments a group command runs (pure): {operation,
+ * method, defaults, render, body, flow, positional, rest, stdinField,
+ * destructive}. operation is null when the words are none of the group's
+ * own: a registry operation (cmdRegistry, in groups-runtime.mjs) then.
+ */
+export function resolveGroup(group, args) {
+    const table = GROUPS[group];
+    let words = 0;
+    if (isWord(args[0]) && isWord(args[1]) && table[`${args[0]} ${args[1]}`]) words = 2;
+    else if (isWord(args[0]) && table[args[0]]) words = 1;
+    else if ((isWord(args[0]) || !Object.keys(table).length) && registryGroupsOf(group).length) return { operation: null, flow: null, destructive: false };
+    else if (isWord(args[0])) {
+        throw new Error(`Unknown ${group} command: ${args[0]}. Use ${Object.keys(table).join(', ')}`);
+    }
+    const sub = words ? args.slice(0, words).join(' ') : Object.keys(table)[0];
+    const { operation, trailing, method, defaults, text, render, body, flow, valueFlags, destructive } = entryOf(table[sub], sub);
+    const { positional, rest } = splitPositional(args.slice(words), valueFlags);
+    let stdinField = null;
+    if (trailing.length && positional.length >= trailing.length) {
+        const fields = positional.splice(positional.length - trailing.length);
+        fields.forEach((value, i) => {
+            if (value === '-') stdinField = trailing[i];
+            else rest.push(`${trailing[i]}${text ? '==' : '='}${value}`);
+        });
+    }
+    return { operation, method, defaults, render, body, flow, positional, rest, stdinField, destructive };
+}
+
+// A wrapper's arguments split in two (pure), the same split ops.mjs's own
+// splitPositional makes: bare words (and "-") that fill path parameters, and
+// everything else (key=value, flags, a flow's own valueFlags). Kept here,
+// not imported from ops.mjs, so this module stays free of the SDK's own
+// load (sdk.mjs's top-level await): command-table.mjs needs only this and
+// resolveGroup/entryOf at --version/--help, neither of which runs a route.
+const VALUE_FLAGS = new Set(['--data', '--file', '--method', '-X']);
+function splitPositional(args, valueFlags = []) {
+    const positional = [];
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--') {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        if (VALUE_FLAGS.has(arg) || valueFlags.includes(arg)) {
+            rest.push(arg);
+            if (i + 1 < args.length) rest.push(args[++i]);
+        } else if ((arg.startsWith('-') && arg !== '-') || /^[^=:]+?(:=|==|=)/.test(arg)) rest.push(arg);
+        else positional.push(arg);
+    }
+    return { positional, rest };
+}