@automaton-labs/aib 0.0.5 → 0.0.7

package/dist/workers/control-plane/client-config.default.json

@@ -0,0 +1,3 @@
+{
+  "schemaVersion": 1
+}

package/dist/workers/product-storage.js

@@ -0,0 +1 @@
+"use strict";var o=exports&&exports.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.productStorageRoot=u;const n=o(require("node:os")),t=o(require("node:path")),r="aib",s="AIB_PRODUCT_STORAGE_DIR";function u(){const e=process.env[s];return e?.trim()?t.default.resolve(e):process.platform==="win32"&&process.env.LOCALAPPDATA?t.default.join(process.env.LOCALAPPDATA,r):process.env.XDG_STATE_HOME?t.default.join(process.env.XDG_STATE_HOME,r):t.default.join(n.default.homedir(),".local","state",r)}

package/dist/workers/registry.js

@@ -0,0 +1 @@
+"use strict";var w=exports&&exports.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.defaultWorkerRegistryPath=E,exports.readWorkerRegistry=p,exports.resolveWorkerRoute=g,exports.parseWorkerRegistry=h;const d=w(require("node:fs")),c=w(require("node:path")),u=require("../shared/errors"),_=require("./product-storage");function E(){return c.default.join((0,_.productStorageRoot)(),"workers","worker-routes.json")}function p(e=E()){if(!d.default.existsSync(e))throw new u.CliError("WORKER_REGISTRY_NOT_FOUND","Worker registry was not found.",{registryPath:e,hint:"Run the control-plane worker with --manifest to fetch and activate remote worker routes."});let r;try{r=JSON.parse(d.default.readFileSync(e,"utf8"))}catch(t){throw new u.CliError("WORKER_REGISTRY_MALFORMED","Worker registry is not valid JSON.",{registryPath:e,error:t instanceof Error?t.message:String(t)})}return h(r,e)}function g(e){const r=c.default.resolve(e.registryPath??E()),t=p(r),o=t.routes.find(s=>s.route===e.route);if(!o)throw new u.CliError("WORKER_ROUTE_NOT_FOUND",`Worker route was not found: ${e.route}`,{route:e.route,registryPath:r,availableRoutes:t.routes.map(s=>s.route).sort()});if(!o.enabled)throw new u.CliError("WORKER_ROUTE_DISABLED",`Worker route is disabled: ${e.route}`,{route:e.route,registryPath:r});if(o.minCliVersion&&!v(e.cliVersion,o.minCliVersion))throw new u.CliError("WORKER_ROUTE_INCOMPATIBLE",`Worker route requires AIB ${o.minCliVersion}.`,{route:e.route,registryPath:r,cliVersion:e.cliVersion,minCliVersion:o.minCliVersion});const i=(0,_.productStorageRoot)(),n=O(i,o,r);if(!d.default.existsSync(n)||!d.default.statSync(n).isFile())throw new u.CliError("WORKER_ENTRY_NOT_FOUND","Worker entry file was not found.",{route:e.route,registryPath:r,entry:o.entry,script:n});return{registryPath:r,productStorageRoot:i,route:o,script:n}}function O(e,r,t){if(r.entry.startsWith("worker-bundle:")){const i=r.entry.slice(14);if(!i||!/^[a-zA-Z0-9._-]+$/.test(i))throw new u.CliError("WORKER_BUNDLE_ENTRY_INVALID","Worker bundle entry is invalid.",{route:r.route,registryPath:t,entry:r.entry});const n=c.default.join(e,"workers","bundles",i,"activation-status.json"),s=I(n),a=s?.active&&typeof s.active=="object"&&!Array.isArray(s.active)?s.active:null,l=typeof a?.entry=="string"?a.entry:null;if(!l)throw new u.CliError("WORKER_BUNDLE_NOT_ACTIVE","Worker bundle has no active version.",{route:r.route,workerId:i,statusPath:n});const f=m(e,l);if(!f)throw new u.CliError("WORKER_BUNDLE_ENTRY_UNSAFE","Worker bundle active entry must resolve inside product storage.",{route:r.route,workerId:i,statusPath:n,activeEntry:l});return f}const o=m(e,r.entry);if(!o)throw new u.CliError("WORKER_ENTRY_UNSAFE","Worker entry must resolve inside product storage.",{route:r.route,registryPath:t,entry:r.entry,productStorageRoot:e});return o}function h(e,r="<memory>"){const t=W(e,"worker registry");if(t.schemaVersion!==1)throw new u.CliError("WORKER_REGISTRY_INVALID","Worker registry schemaVersion must be 1.",{registryPath:r});const o=t.routes;if(!Array.isArray(o))throw new u.CliError("WORKER_REGISTRY_INVALID","Worker registry routes must be an array.",{registryPath:r});const i=o.map((s,a)=>b(s,a,r)),n=new Set;for(const s of i){if(n.has(s.route))throw new u.CliError("WORKER_REGISTRY_INVALID",`Duplicate worker route: ${s.route}`,{registryPath:r,route:s.route});n.add(s.route)}return{schemaVersion:1,...typeof t.generatedAt=="string"?{generatedAt:t.generatedAt}:{},...typeof t.registryVersion=="string"?{registryVersion:t.registryVersion}:{},routes:i}}function b(e,r,t){const o=W(e,`worker route ${r}`),i=R(o.route,"route",r,t),n=R(o.workerId,"workerId",r,t),s=R(o.version,"version",r,t),a=R(o.entry,"entry",r,t),l=o.argsMode===void 0?"passthrough":o.argsMode,f=o.output===void 0?"json":o.output;if(l!=="passthrough")throw y("argsMode must be passthrough",r,t);if(f!=="json")throw y("output must be json",r,t);return{route:i,workerId:n,version:s,entry:a,argsMode:"passthrough",output:"json",enabled:o.enabled!==!1,...typeof o.minCliVersion=="string"&&o.minCliVersion.trim()?{minCliVersion:o.minCliVersion}:{},capabilities:Array.isArray(o.capabilities)?o.capabilities.filter(k=>typeof k=="string"):[]}}function W(e,r){if(!e||typeof e!="object"||Array.isArray(e))throw new u.CliError("WORKER_REGISTRY_INVALID",`${r} must be an object.`);return e}function R(e,r,t,o){if(typeof e=="string"&&e.trim())return e;throw y(`${r} is required`,t,o)}function y(e,r,t){return new u.CliError("WORKER_REGISTRY_INVALID",`Invalid worker route at index ${r}: ${e}.`,{registryPath:t,index:r})}function m(e,r){const t=r.replace(/\\/g,"/");if(!t||t.startsWith("/")||t.split("/").includes(".."))return null;const o=c.default.resolve(e),i=c.default.resolve(o,t),n=c.default.relative(o,i);return n&&!n.startsWith("..")&&!c.default.isAbsolute(n)?i:null}function I(e){try{const r=JSON.parse(d.default.readFileSync(e,"utf8"));return r&&typeof r=="object"&&!Array.isArray(r)?r:null}catch{return null}}function v(e,r){const t=r.match(/^>=\s*(\d+)\.(\d+)\.(\d+)$/);if(!t)return e===r;const o=N(e),i=t.slice(1).map(n=>Number(n));for(let n=0;n<3;n+=1){const s=o[n]??0,a=i[n]??0;if(s>a)return!0;if(s<a)return!1}return!0}function N(e){const r=e.match(/(\d+)\.(\d+)\.(\d+)/);return r?r.slice(1).map(t=>Number(t)):[0,0,0]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automaton-labs/aib",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "CLI for discovering and calling the local aib IDE extension runtime.",
   "publishConfig": {
     "access": "public"
@@ -15,14 +15,16 @@
     "scripts/postinstall.cjs",
     "scripts/provision-runtime.cjs",
     "runtimes/launcher",
+    "runtimes/tools",
     "README.md",
     "package.json"
   ],
   "scripts": {
-    "build": "tsc -p . && node scripts/copy-managed-host-assets.cjs",
-    "build:package": "node ../../scripts/package/clean-paths.cjs dist && tsc -p tsconfig.package.json && node scripts/copy-managed-host-assets.cjs && node ../../scripts/package/minify-js.cjs dist",
-    "typecheck": "tsc -p . --noEmit",
+    "build": "npm --silent --prefix ../control-plane-contracts run build && tsc -p . && node scripts/copy-managed-host-assets.cjs && node scripts/copy-control-plane-worker.cjs",
+    "build:package": "npm --silent --prefix ../control-plane-contracts run build && node ../../scripts/package/clean-paths.cjs dist && tsc -p tsconfig.package.json && node scripts/copy-managed-host-assets.cjs && node scripts/copy-control-plane-worker.cjs --minify && node ../../scripts/package/minify-js.cjs dist",
+    "typecheck": "npm --silent --prefix ../control-plane-contracts run build && tsc -p . --noEmit",
     "postinstall": "node scripts/postinstall.cjs",
+    "sync:tool-runtimes": "node ../../scripts/runtime/sync-tool-runtimes.cjs",
     "prepack": "npm run build:package && node scripts/copy-extension-vsix.cjs",
     "pack:local": "npm pack --pack-destination ../../.tmp"
   },

package/runtimes/tools/rg/manifest.json

@@ -0,0 +1,36 @@
+{
+  "schema": 1,
+  "tool": "rg",
+  "version": "15.1.0",
+  "source": {
+    "repo": "BurntSushi/ripgrep",
+    "tag": "15.1.0"
+  },
+  "platforms": {
+    "win32-x64": {
+      "asset": "ripgrep-15.1.0-x86_64-pc-windows-msvc.zip",
+      "sha256": "124510b94b6baa3380d051fdf4650eaa80a302c876d611e9dba0b2e18d87493a",
+      "executable": "rg.exe"
+    },
+    "linux-x64": {
+      "asset": "ripgrep-15.1.0-x86_64-unknown-linux-musl.tar.gz",
+      "sha256": "1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599",
+      "executable": "rg"
+    },
+    "linux-arm64": {
+      "asset": "ripgrep-15.1.0-aarch64-unknown-linux-gnu.tar.gz",
+      "sha256": "2b661c6ef508e902f388e9098d9c4c5aca72c87b55922d94abdba830b4dc885e",
+      "executable": "rg"
+    },
+    "darwin-x64": {
+      "asset": "ripgrep-15.1.0-x86_64-apple-darwin.tar.gz",
+      "sha256": "64811cb24e77cac3057d6c40b63ac9becf9082eedd54ca411b475b755d334882",
+      "executable": "rg"
+    },
+    "darwin-arm64": {
+      "asset": "ripgrep-15.1.0-aarch64-apple-darwin.tar.gz",
+      "sha256": "378e973289176ca0c6054054ee7f631a065874a352bf43f0fa60ef079b6ba715",
+      "executable": "rg"
+    }
+  }
+}

package/runtimes/tools/rtk/manifest.json

@@ -0,0 +1,36 @@
+{
+  "schema": 1,
+  "tool": "rtk",
+  "version": "0.42.3",
+  "source": {
+    "repo": "rtk-ai/rtk",
+    "tag": "v0.42.3"
+  },
+  "platforms": {
+    "win32-x64": {
+      "asset": "rtk-x86_64-pc-windows-msvc.zip",
+      "sha256": "334d05a6662576a84a78b771aee0749202eacabd87acbb9fd266e6a5466f700a",
+      "executable": "rtk.exe"
+    },
+    "linux-x64": {
+      "asset": "rtk-x86_64-unknown-linux-musl.tar.gz",
+      "sha256": "5df764a633709cb85d248258d085d24ec95faa8bca0e6835a93cd57cadc4eb9e",
+      "executable": "rtk"
+    },
+    "linux-arm64": {
+      "asset": "rtk-aarch64-unknown-linux-gnu.tar.gz",
+      "sha256": "2b7fa09d06f8dbf334c55482fad2e7ce4a1f8564bc9ed1f65d9f5992db8e5527",
+      "executable": "rtk"
+    },
+    "darwin-x64": {
+      "asset": "rtk-x86_64-apple-darwin.tar.gz",
+      "sha256": "7c72d05cfc71b7e2f20755b3754b728acecc7c0b1fbbb08757828f9e7bedd81a",
+      "executable": "rtk"
+    },
+    "darwin-arm64": {
+      "asset": "rtk-aarch64-apple-darwin.tar.gz",
+      "sha256": "d47823afb25919e4e60838c5622e88ffa6536bc0b36a34a3f928bdccac40f614",
+      "executable": "rtk"
+    }
+  }
+}

package/scripts/provision-runtime.cjs

@@ -223,7 +223,31 @@ function defaultManifestUrl() {
 function runtimeComplete() {
   return fs.existsSync(path.join(runtimesDir, "code-server", "node_modules", "code-server", "out", "node", "entry.js"))
     && Boolean(findPackagedBrowserRuntime())
-    && Boolean(findPackagedNodeRuntime());
+    && Boolean(findPackagedNodeRuntime())
+    && runtimePlatformStatus().ok;
+}
+
+function runtimePlatformStatus() {
+  const markerPath = path.join(runtimesDir, ".aib-runtime-platform.json");
+  if (!fs.existsSync(markerPath)) {
+    return { ok: true, reason: "missing", expectedPlatformKey: platformKey, actualPlatformKey: null };
+  }
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+    const actualPlatformKey = typeof marker.platformKey === "string"
+      ? marker.platformKey
+      : typeof marker.platform === "string" && typeof marker.arch === "string"
+        ? `${marker.platform}-${marker.arch}`
+        : null;
+    return {
+      ok: actualPlatformKey === platformKey,
+      reason: actualPlatformKey === platformKey ? "ok" : "mismatch",
+      expectedPlatformKey: platformKey,
+      actualPlatformKey
+    };
+  } catch {
+    return { ok: false, reason: "invalid", expectedPlatformKey: platformKey, actualPlatformKey: null };
+  }
 }
 
 function findPackagedNodeRuntime() {

package/dist/help/json/docs/basics.md

@@ -1,15 +0,0 @@
-# Basics
-
-Use the active session while you work.
-Reuse captured inputs when editing them is cheaper than rebuilding large JSON.
-
-Examples are patterns, not limits.
-Feature sections show common high-value uses, not every valid use.
-Adapt requests to the task: combine features, batch related questions, and skip steps when you already have enough context.
-
-Prefer batch JSON instead of inline calls.
-One request can inspect/mutate several files/entities and save reusable outputs.
-Use one-off commands only for small checks/changes.
-
-For mutations, aib asks TS/IDE refactors to update affected references and imports.
-After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or the build/checks show a real issue.

package/dist/help/json/docs/config-setup.aliases.md

@@ -1,56 +0,0 @@
-# Config Setup: Aliases
-
-If you have not just checked the full config, check current aliases:
-
-aib config aliases
-
-pathAliases define short request aliases for paths agents repeat in AIB commands.
-Use them to reduce input tokens for repeated inspect and mutation work.
-
-Aliases are for AIB request paths.
-They do not change TypeScript imports by themselves.
-For import style after mutations, use importRules.
-
-Check TypeScript aliases for hints:
-
-aib reveal tsaliases
-
-Use this to see existing tsconfig paths and baseUrl values.
-They can reveal stable work areas, but they are not a list to copy.
-
-Add pathAliases for long paths that are likely to appear repeatedly in AIB requests.
-Prefer aliases for real work areas, package roots, or deep directories.
-
-A good alias:
-- saves meaningful path tokens;
-- points to a stable work area;
-- is easy to recognize later.
-
-A bad alias:
-- duplicates a short path like "src": "src", "packages": "packages", "scripts": "scripts";
-- points to a rarely used folder;
-- mirrors the directory tree without a workflow reason.
-
-Having 20-30 good aliases is fine for a large repo or monorepo.
-
-Example:
-
-"pathAliases": {
-  "wstore": "apps/web/src/shared/store",
-  "wapi": "apps/web/src/shared/api",
-  "whooks": "apps/web/src/shared/utils/hooks",
-  "pmail": "packages/email/src",
-  "putils": "packages/utils/src",
-  "arules": "docs/agent/rules"
-}
-
-After editing aib.json, run:
-
-aib sync
-
-Verify aliases with a small tree or inspect request:
-
-aib inspect --stdin
-
-Input:
-tree @<alias> depth=3 +onlyDirs limit=80

package/dist/help/json/docs/config-setup.excludes.md

@@ -1,45 +0,0 @@
-# Config Setup: Excludes
-
-Tree excludes affect directory and file discovery output.
-Graph excludes affect graph counts, hubs, entrypoints, leaves, edges, imports, importedBy, and saved graph views.
-
-Built-in excludes already skip common noise such as node_modules, .git, dist, build, out, and .tmp.
-Add config excludes for repository-specific noise.
-
-For example, if the user often creates hard-copy directories or backup files before risky edits, those copies can make tree and graph output noisy.
-Exclude them explicitly:
-
-"inspect.tree.onlyDirs.exclude": [
-  "**/*copy",
-  "**/*copy/**"
-],
-"inspect.tree.files.exclude": [
-  "**/* copy.ts",
-  "**/*.generated.ts"
-],
-"inspect.graph.exclude": [
-  "**/* copy.ts",
-  "**/*.generated.ts",
-  "src/generated/**"
-]
-
-Prefer narrow patterns for known noise:
-- generated files;
-- local copy/backup folders;
-- build artifacts not already skipped by defaults;
-- vendored or checked-in output.
-
-These are common cases, not mandatory rules.
-If the repository needs one of these areas for reasoning or mutation impact checks, do not exclude it.
-
-Do not exclude broad source areas to make output smaller.
-If output is too large, use scope, depth, limit, graph view, or graph toggles first.
-
-After editing aib.json, run:
-
-aib sync
-
-Then verify with a compact tree request and the graph view that was noisy.
-
-If excluded paths still appear, check the glob pattern against repo-relative paths.
-If important source disappeared, narrow or remove the exclude.

package/dist/help/json/docs/config-setup.import-normalize.md

@@ -1,86 +0,0 @@
-# Config Setup: Import Normalize
-
-Configure import normalization intent.
-
-importNormalize defines default normalization rules for explicit aib imports normalize commands.
-Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
-
-It does not run automatically during move/modulePlan.
-Use importRules for mutation-time import cleanup.
-
-Set importNormalize when the intended cleanup has project meaning:
-- adopting a new tsconfig alias across a project area;
-- converting an area to aliases;
-- converting scripts/tools or extracted modules to relative imports;
-- excluding generated or bundled output from normalization.
-
-For tiny one-file checks, inline options are fine.
-Before wider cleanup, put the intended rule in config and preview the smallest useful scope.
-
-Fields:
-scope        repo-relative file or directory scope; most specific scope wins
-to           relative|alias|shortestAlias
-preferAlias  tsconfig paths pattern used when to=alias
-exclude      files, directories, or glob-like patterns to skip
-
-to:
-relative       rewrite resolved local imports to relative paths
-alias          rewrite resolved local imports to a matching tsconfig alias
-shortestAlias  rewrite to the shortest valid alias specifier
-
-preferAlias:
-@shared/*      prefer one alias pattern when several aliases can resolve the same file
-
-Alias cleanup:
-
-"importNormalize": [
-  {
-    "scope": "src",
-    "to": "shortestAlias",
-    "preferAlias": "@/*",
-    "exclude": [
-      "src/generated",
-      "src/**/dist"
-    ]
-  }
-]
-
-Relative cleanup for scripts/tools:
-
-"importNormalize": [
-  {
-    "scope": "scripts",
-    "to": "relative",
-    "exclude": [
-      "scripts/**/*.cjs",
-      "scripts/**/*.mjs"
-    ]
-  }
-]
-
-If you have not just checked config rules, run:
-
-aib config rules
-
-After editing aib.json, run:
-
-aib sync
-
-Then preview the smallest useful scope before applying:
-
-aib imports normalize preview <scope>
-
-Preview shows counts, sample import rewrites, a planId, and the apply command.
-It does not change project files.
-
-If preview changes imports outside the intended area, narrow scope or add exclude.
-
-If preview does not use the expected alias, check tsconfig aliases:
-
-aib reveal tsaliases
-
-If the config and aliases look correct but preview still looks stale or strange, run:
-
-aib sync
-
-Then preview again.

package/dist/help/json/docs/config-setup.import-rules.md

@@ -1,96 +0,0 @@
-# Config Setup: Import Rules
-
-Use this when move/modulePlan creates imports that do not match the repository style.
-
-Do not keep fixing the same generated import style by hand.
-Tune importRules, sync config, then retry the smallest useful mutation before continuing larger mutation work.
-
-Check current config:
-
-aib config rules
-
-importRules control imports created or expanded by move/modulePlan mutation cleanup.
-They do not rewrite the whole project.
-
-AIB starts from IDE/TS import preferences.
-For mutation cleanup, matching importRules in aib.json take priority.
-Do not assume IDE/TS defaults match the repo style.
-
-Fields:
-scope      repo-relative file or directory scope; most specific scope wins
-specifier  relative|shortest|project-relative|non-relative
-ending     auto|minimal|index|js
-builtin    node|bare
-unusedImports  remove|preserve
-
-Defaults:
-specifier omitted      IDE/TS decides
-ending omitted         IDE/TS decides
-builtin omitted        keep TS/project builtin style
-unusedImports omitted  keep unused imports
-
-specifier:
-relative          best for local relative imports
-shortest          best for shortest valid alias/path output
-project-relative  best for root-relative project imports
-non-relative      best for package or alias imports
-
-ending:
-minimal  best for extensionless TS imports
-js       best for ESM-style TS projects that require .js
-auto     leaves the decision to TypeScript
-index    best for explicit index import style
-
-builtin:
-node        path -> node:path; best for explicit Node builtin imports
-bare        node:path -> path; best for bare Node builtin imports
-omit field  keeps TypeScript/project output; add builtin if agents keep fixing this manually
-
-unusedImports:
-remove    clean unused imports in mutation-touched files
-preserve  keep unused imports
-omit      same as preserve
-
-Mutation-touched files are files where TS produced edits: source/target files and any reference/update files TS changed.
-Recommended value: remove
-
-If the repository has one import style, use one broad rule:
-
-"importRules": [
-  {
-    "scope": ".",
-    "specifier": "shortest",
-    "ending": "auto",
-    "builtin": "node",
-    "unusedImports": "remove"
-  }
-]
-
-Use scoped rules only when areas differ by style, for example packages use aliases but scripts use relative imports:
-
-"importRules": [
-  {
-    "scope": "packages",
-    "specifier": "shortest",
-    "ending": "auto",
-    "builtin": "node",
-    "unusedImports": "remove"
-  },
-  {
-    "scope": "scripts",
-    "specifier": "relative",
-    "ending": "auto",
-    "builtin": "node",
-    "unusedImports": "remove"
-  }
-]
-
-Use the most specific scope that matches the real convention.
-Do not add scoped rules just because directories exist.
-
-After editing aib.json, run:
-
-aib sync
-
-Then rerun the smallest affected move/modulePlan preview or execute request.
-If imports are still wrong, update importRules again before doing more manual cleanup.

package/dist/help/json/docs/config-setup.tsconfigs.md

@@ -1,33 +0,0 @@
-# Config Setup: TypeScript Configs
-
-AIB syncs and watches visible tsconfigs.
-Keep real app/package configs visible.
-Exclude nested workspaces, seed projects, snapshots, backups, copied apps, or other non-primary projects.
-
-Do not exclude real package/app configs just to reduce output.
-
-Check which TypeScript configs AIB will sync and watch:
-
-aib reveal tsconfigs +all
-
-If output includes non-primary projects, exclude them:
-
-"sync.tsconfig.exclude": [
-  "dev-seed/**",
-  "snapshots/**"
-]
-
-After editing aib.json, run:
-
-aib sync
-
-Then check again:
-
-aib reveal tsconfigs +all
-
-Visible tsconfigs should describe the active project surface.
-Excluded tsconfigs should be things the agent should not use for setup decisions.
-
-Use +nec only when you need to compare visible configs with config-excluded configs:
-
-aib reveal tsconfigs +nec

package/dist/help/json/docs/dsl.md

@@ -1,25 +0,0 @@
-# DSL
-
-DSL request model:
-- directives set defaults for following requests
-- each request line can override defaults with key=value
-- +flag means true
-- -flag means false
-- file/imports/exports/members/code/deps accept a path as the first positional argument; examples below use this shape.
-- Use @file when several following operations share the same file.
-- For one-off file operations, pass the path directly.
-
-Syntax:
-@file <path>               default file
-@source <path>             default sourceFile for mutations
-op arg arg key=value       request
-+flag                      boolean true
--flag                      boolean false
->name                      save reusable artifact when supported
-old->new                   rename pair
-Parent.member              parent-qualified member
-Parent.{a,b}               several members under one parent
-key=[a,b]                  list value for repeatable fields
-file="path with spaces.ts" quote values with spaces
-detail=sum|loc|code        aliases for summary|locations|code
-from=...                   alias for fromFile