Mx createfile

.agents/skills/sas/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sas
-description: Expert guidance for the SAS programming language — DATA step, PROC SQL, macro language, formats, ODS, and common procedures. Pure SAS syntax only; contains no SASjs-framework content. Use when writing, reviewing, debugging, or refactoring .sas programs, or when asked SAS language questions.
+description: Expert guidance for the SAS programming language — DATA step, PROC SQL, macro language, formats, ODS, and common procedures. Pure SAS syntax only, no SASjs-framework content. Use when writing, reviewing, or debugging .sas programs, or answering SAS language questions.
 ---
 
 # SAS Language
@@ -49,6 +49,7 @@ These follow the @sasjs/core coding standards — apply them to all SAS code:
 
 - Note when code differs between SAS 9.4 and Viya (e.g. CAS actions vs procs, `proc casutil` for sashdat loading, no X command on locked-down servers)
 - Avoid hard-coded physical paths and engine-specific options unless asked
+- No open macro code with if/else logic: wrap branching blocks in `%macro ... %mend` and call them — open `%if`/`%else` does not behave as expected in all SAS environments.
 
 ## Common pitfalls to flag when reviewing
 

.agents/skills/sasjs-adapter/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sasjs-adapter
-description: Frontend/Node integration with SAS backends using @sasjs/adapter — configuring the SASjs class, authentication (SAS 9, Viya, SASjs server), executing requests with input/output tables, file upload, and session/context management. Use when writing TypeScript/JavaScript that calls SAS services or jobs.
+description: Frontend/Node integration with SAS backends using @sasjs/adapter — configuring the SASjs class, authentication (SAS 9, Viya, SASjs server), requests with input/output tables, file upload, and session management. Use when writing TypeScript/JavaScript that calls SAS services or jobs.
 ---
 
 # @sasjs/adapter
@@ -54,3 +54,15 @@ const response = await sasjs.request('services/common/getdata', {
 - Always handle `response.status` / error responses — SAS-side errors (e.g. from `%mp_abort`) come back in the JSON, not necessarily as HTTP errors.
 - For large payloads prefer CSV upload or streamed files over JSON input tables.
 - Keep `appLoc` consistent with the `appLoc` in `sasjsconfig.json` used to deploy.
+
+## Important: request() inputs are ALWAYS tables
+
+Every key in the `data` object of `sasjs.request(path, data)` is serialized via the `sasjs_tables` CSV mechanism and arrives in SAS as a **work dataset named after the key** — even scalar values. You cannot pass ad-hoc macro variables this way; services must read inputs from the work table (e.g. `data _null_; set work.config; call symputx('rootdir', rootdir); run;`). Output column names in `response.result.<table>` come back UPPERCASE (SAS dataset semantics).
+
+## Using the adapter without a bundler (zero-build / strict CSP frontends)
+
+The package root `index.js` is a UMD bundle exposing a global `SASjs`. Pattern (from the minimal seed app):
+
+1. `"prepare": "cp node_modules/@sasjs/adapter/index.js src/sasjs.js"` in package.json (runs on `npm i`).
+2. `<script src="sasjs.js"></script>` before your app script.
+3. Configure via a hidden custom element: `<sasjs serverType="SASJS" appLoc="/Public/app/myapp" debug="false"></sasjs>` and read attributes with `document.querySelector('sasjs')`. When the app is streamed by SAS itself, omit `serverUrl` — same-origin requests just work (CSP `default-src 'self'` safe).

.agents/skills/sasjs-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sasjs-cli
-description: Using the @sasjs/cli command-line tool to create, compile, build, deploy, run, and test SASjs projects against SAS 9, Viya, and SASjs server targets. Use for any sasjs <command> usage, CI/CD deployment pipelines, target/auth configuration, sasjsconfig.json manipulation, service packs, or frontend streaming builds.
+description: Using the SASjs CLI (@sasjs/cli) to create, compile, build, deploy, run, and test SASjs projects against SAS 9, Viya, and SASjs server targets. Use for any `sasjs <command>` usage, CI/CD pipelines, target/auth config, sasjsconfig.json, service packs, or frontend streaming builds.
 ---
 
 # @sasjs/cli
@@ -47,7 +47,14 @@ sasjs cbd                 # compile + build + deploy in one step (-t viya etc.)
 
 ## Conventions
 
+- Test coverage is generated only from a `sasjs compile` (or `sasjs c`). It accepts a target (`-t <target>`), but nothing is deployed to that target — compilation and coverage are fully local/offline, so no server needs to be available or reachable. Missing macro dependencies (e.g. `mp_ds2csv.sas`) mean `@sasjs/core` isn't installed — run `npm i` first.
+
 - Dependencies are declared in doxygen headers: `<h4> SAS Macros </h4>`, `<h4> SAS Files </h4>`, `<h4> SAS Folders </h4>`, and `@li item` entries — the CLI builds the dependency tree from these.
 - `sasjs compile` output goes to the `sasjsbuild/` folder (git-ignore it); `sasjsresults/` holds test/run outputs.
 - CI/CD: `sasjs cbd -t viya` is the standard deploy step; combine with `sasjs servicepack deploy` for artefact-based releases.
 - Exit codes are non-zero on failure — safe for pipelines.
+
+## Gotchas
+
+- Run `npm i` before `sasjs cb` — macro dependency resolution needs `node_modules/@sasjs/core` present, and `@sasjs/core` (and `@sasjs/adapter` if used) must be listed in `package.json`.
+- Credentials files are per-target: `.env.<targetname>` (e.g. `.env.server`) with `CLIENT`, `ACCESS_TOKEN`, `REFRESH_TOKEN`. Never commit them — gitignore `.env*`.

.agents/skills/sasjs-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sasjs-core
-description: Standards and conventions for the @sasjs/core SAS macro library (mf_*, mp_*, mm*, ms_*, mv_* macros). Use when writing or editing SAS macros in a sasjs/core-style repo, when choosing an existing macro instead of reinventing one, or when asked about the sasjs/core build, lint, doxygen header, or testing conventions.
+description: Standards and conventions for the @sasjs/core SAS macro library (mf_*, mp_*, mm*, ms_*, mv_* macros). Use when writing or editing SAS macros in a sasjs/core-style repo, picking an existing macro over reinventing one, or the sasjs/core build, lint, doxygen, and testing conventions.
 ---
 
 # @sasjs/core — SAS Macro Library
@@ -13,6 +13,7 @@ description: Standards and conventions for the @sasjs/core SAS macro library (mf
 - Macro definitions must use parentheses: `%macro x();` not `%macro x;`
 - Macro *calls* are NOT terminated with a semicolon: `%my_macro()` not `%my_macro();`
 - All macro variables must be declared `%local` to prevent scope leakage
+- Always use `mf_getuniquefileref` when assigning filerefs, and `mf_getuniquelibref` when assigning librefs (never hardcode or hand-roll unique references)
 - 2-space indentation, no tabs, no trailing spaces, no invisible characters, max line length 300 (hard lint limit) but keep lines to 80 chars max where possible
 - Every file must have a Doxygen header:
 
@@ -49,6 +50,8 @@ description: Standards and conventions for the @sasjs/core SAS macro library (mf
 
 Use `mf_` macros when the macro returns a value usable in an expression; use `mp_` for procedural macros that generate code/statements.
 
+**Cross-suite rule:** `mp_` macros must never reference `mx_` macros. Platform dispatching (SAS 9 / Viya / SASjs server) belongs in the `mx_` suite, which delegates to `ms_`/`mv_`/PROC STP per platform. If an `mp_` macro seems to need platform-specific behaviour, the macro itself belongs in `xplatform/` as an `mx_` macro instead.
+
 ## Reuse before writing
 
 Before writing a new macro, check the library for an existing one — common utilities already exist, e.g. `mp_abort` (the deprecated `mf_abort` is retained for backwards compatibility — don't use it in new code), `mf_existds`, `mf_existvar`, `mf_existfileref`, `mf_getuser`, `mp_jsonout` (SAS datasets → JSON for `_webout`), `mp_ds2ddl`, `mp_hashdataset`. Platform-specific variants exist under `meta/`, `viya/`, `server/` and are selected at compile time by the CLI.
@@ -72,9 +75,25 @@ When `%mp_abort` is called from within a `%include` block, SAS cannot exit clean
 
 Note: `%include`s inside macros should be performed with `%mp_include()` so the `_SYSINCLUDEFILEDEVICE` indicator is set and the abort dataset (`work.mp_abort_errds`) is passed back to the calling program.
 
+## Testing macros (mandatory conventions)
+
+- **Always apply `%mp_assertscope` around the macro under test** to catch scope leakage (macro variables must stay `%local`):
+
+```sas
+%mp_assertscope(SNAPSHOT)
+%mx_foo(args)
+%mp_assertscope(COMPARE,
+  desc=Test 1: mx_foo does not leak scope,
+  outds=work.test_results
+)
+```
+
+- Assertions go to `work.test_results` via `%mp_assert(iftrue=(...), desc=..., outds=work.test_results)`.
+
 ## Lint and build
 
 - Run `sasjs lint` after every change; do not consider work done until it passes
 - NEVER bump the version in `package.json` (semantic-release handles it)
 - Do NOT edit generated files by hand: `all.sas`, `mc_*.sas`, the `lua/` wrappers, and `sasjsbuild/` outputs are produced by the CI build
 - Markdown files: never hard-wrap; one paragraph per line
+

.agents/skills/sasjs-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sasjs-framework
-description: Building full SASjs applications — project structure, sasjsconfig.json, services/jobs/macros folders, multi-target (SAS 9 / Viya / SASjs server) configuration, streaming frontends, mocks and tests. Use when creating or modifying a SASjs app, editing sasjsconfig.json, writing backend services that return JSON to a web frontend, or structuring a project like Data Controller.
+description: Building full SASjs applications — project structure, sasjsconfig.json, services/jobs/macros folders, multi-target (SAS 9 / Viya / SASjs server) configuration, streaming frontends, mocks and tests. Use when creating or modifying a SASjs app, editing sasjsconfig.json, or writing backend services returning JSON to a web frontend.
 ---
 
 # SASjs Framework — Building SASjs Applications
@@ -79,12 +79,15 @@ If the abort happens inside a `%include` block, SAS cannot exit to `_webout` cle
 
 - Run `sasjs lint` after touching any `.sas` file; fix all warnings in files you touched.
 - The linter enforces 2-space indentation everywhere, including continuation lines inside `/* ... */` block comments — never align comment text with 3+ spaces.
-- Add tests under `sasjs/tests` and run `sasjs test` for backend logic changes.
+- Add tests and run `sasjs test` for backend logic changes. When testing macros, always wrap the macro under test with `%mp_assertscope(SNAPSHOT)` / `%mp_assertscope(COMPARE, ...)` to catch macro-variable scope leakage, and wrap any platform-branching code in `%macro` wrappers (no open conditional macro code in test programs).
 - Provide mocks in `sasjs/mocks` so the frontend can be developed without a live SAS server.
 - Never auto-commit or bump versions; releases are pipeline-driven (conventional commits).
 - Markdown files: no hard wrapping — one paragraph per line.
 - Apps must work offline/on-prem: no external CDN assets in the frontend bundle.
 
 ## Reference implementations
 
-Look at existing apps for patterns: folder layouts, `sasjsconfig.json` multi-target setups, service structure, streaming builds, and test/mock conventions (e.g. Data Controller `dc`, `dwp_frs`, `plato`).
+Look at existing apps for patterns: folder layouts, `sasjsconfig.json` multi-target setups, service structure, streaming builds, and test/mock conventions, eg:
+* https://git.datacontroller.io/dc/dc
+* https://github.com/sasjs/react-seed-app
+* https://github.com/sasjs/macro-dash

.agents/skills/sasjs-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sasjs-server
-description: Installing, configuring, and running @sasjs/server — the open-source NodeJS wrapper around the SAS binary that provides a REST API, filesystem (SASjs Drive), Stored Program execution, and web app streaming. Covers desktop vs server modes, runtime configuration (SAS/JS/Python/R), environment variables, auth (tokens, LDAP), and mock server types. Use when deploying, troubleshooting, or developing against sasjs/server.
+description: Installing, configuring, and running @sasjs/server — the open-source NodeJS wrapper around the SAS binary that provides a REST API, filesystem (SASjs Drive), Stored Program execution, and web app streaming. Covers desktop vs server modes, runtimes (SAS/JS/Python/R), env vars, auth (tokens, LDAP), and mock servers. Use when deploying, troubleshooting, or developing against sasjs/server.
 ---
 
 # @sasjs/server
@@ -44,12 +44,40 @@ Set in `/etc/environment`, exported, prepended to the command, or in a `.env` fi
 | `SAS_OPTIONS` / `SASV9_OPTIONS` | Extra SAS system options auto-applied to sessions (Windows vs Unix), e.g. `-NOXCMD` |
 | `DB_CONNECT` / `DB_TYPE` | MongoDB connection string / type — required for server mode |
 | `AUTH_PROVIDERS` + `LDAP_*` | LDAP auth: `LDAP_URL`, `LDAP_BIND_DN`, `LDAP_BIND_PASSWORD`, `LDAP_USERS_BASE_DN`, `LDAP_GROUPS_BASE_DN` |
-| `CORS` / `WHITELIST` | Enable CORS and whitelist space-separated origins |
-| `MOCK_SERVERTYPE` / `STATIC_MOCK_LOCATION` | Emulate `sas9`/`sasviya` API responses for frontend testing against a sasjs server |
+| `CORS` / `WHITELIST` | CORS is only applied when `CORS=enable`, and only origins in `WHITELIST` (space-separated) receive `Access-Control-Allow-Origin` — an empty whitelist means NO cross-origin calls work |
+| `MOCK_SERVERTYPE` / `STATIC_MOCK_LOCATION` | Emulate `sas9`/`sasviya` API responses for frontend testing against a sasjs server (static canned files only — no logic) |
 
 ## Developing against the API
 
 - Server type for @sasjs/adapter / CLI targets is `SASJS` (`serverType: 'SASJS'`); auth is token-based.
 - The REST API is self-documented via Swagger on the running instance.
 - Server-side execution uses `ms_*` macros from @sasjs/core (e.g. `ms_createfile`, `ms_adduser2group`) — services/jobs deployed by the CLI work as on other platforms.
 - Repo layout (for contributors): `api/` (Express/TypeScript backend: controllers, routes, middlewares, model), `web/` (frontend), `restClient/` (REST examples), `mongo-seed/` (server-mode DB seed).
+
+## Mock services with the JS runtime (no SAS required)
+
+With `RUN_TIMES=js` (and `NODE_PATH` set), any `.js` file on SASjs Drive is an executable Stored Program — this is how react-seed-app / Data Controller provide **mock backends** for frontend development.  Desktop mode (`MODE=desktop`) has no auth, which makes local mocking trivial.
+
+Writing a JS stored program (docs: https://server.sasjs.io/storedprograms/#js-programs):
+
+- The runtime template predeclares `const fs = require('fs')`, `_program`, `weboutPath`, `_SASJS_TOKENFILE`, `_SASJS_WEBOUT_HEADERS`, `_SASJS_USERNAME` / `_SASJS_USERID` / `_SASJS_DISPLAYNAME`, `_METAPERSON`, `_METAUSER`, `SASJSPROCESSMODE`.  **Do NOT redeclare `fs`** — `const fs = require('fs')` in your program crashes it with `Identifier 'fs' has already been declared`.
+- Output: assign a JSON **string** to `_webout` (e.g. `_webout = JSON.stringify({...})`); it is written back only if non-empty.  `console.log()` output is returned in the response `log` (like a SAS log).  Custom response headers can be written as lines to the `_SASJS_WEBOUT_HEADERS` file.
+- Mimic real services by including the standard SASjs automatic fields in the JSON: `_PROGRAM` (from `_program`), `SYSDATE` / `SYSTIME` (format `DDMMMYY` / `HH:mm`), `_METAUSER`, `SASJSPROCESSMODE`.
+- URL/body parameters arrive as `const <name> = \`<value>\`` strings.
+- Input tables (the `sasjs_tables` mechanism) arrive **either** as an inline CSV const **or** — when the adapter sends multipart — as an uploaded `<name>.csv` file in the session folder, referenced by generated module-scope consts (handle BOTH):
+  - `_WEBIN_FILE_COUNT` (always created), `_WEBIN_NAME<n>` (table/field name), `_WEBIN_FILENAME<n>` (original filename), `_WEBIN_FILEREF<n>` (file **contents**, a Buffer from `fs.readFileSync` — call `.toString('utf8')`)
+  - these consts are **not on `globalThis`** — look them up with `typeof` guards or direct `eval()` in module scope (server-side JS, no CSP)
+  - adapter CSV quirks: header row is **space-separated** `name:format.` entries (e.g. `rootdir:$char256.`) — strip the `:format` suffix; lines end CRLF; values containing special characters are wrapped in double quotes with `""` escaping
+- Adapter response shape: `sasjs.request()` resolves with the webout JSON **already unwrapped** — output tables are arrays of row objects directly on the response (`res.mytable[0].COL`).  A table named `result` is perfectly fine (`res.result` is then that array); do NOT add your own `res.result`-unwrapping layer, it breaks exactly that case.
+- Third-party npm packages are NOT resolvable at runtime — bundle the service first (e.g. `npx webpack --mode none --target node --entry <file> --output-path sasjsbuild/... --output-filename <name>.js`), then `sasjs build` / `sasjs deploy`.
+
+Deploying mocks:
+
+- `sasjs fs sync` does NOT work on a JS-only server (it generates and executes SAS code to hash remote files).  Upload files directly via the Drive API instead: `DELETE` then `POST /SASjsApi/drive/file?_filePath=<appLoc>/services/<folder>/<name>.js` (multipart `file` field).  In desktop mode no auth headers are needed; in server mode read the `Authorization` header line from `_SASJS_TOKENFILE`.
+- Mocks can be stateful with the predeclared `fs`.  Prefer real locations over `/tmp`: the SASjs Drive root is derivable from `weboutPath` (`<root>/sessions/<id>/webout.txt` → `path.resolve(weboutPath, '..', '..', '..', 'drive')`), and a mock `configure`-style service can treat a configured folder as a real local path (the server IS local).  `require('path')` and other core modules work (only `fs` is predeclared).
+- A JS program can even call the server's own REST API (`http://127.0.0.1:$PORT/SASjsApi/...`) — e.g. to rewrite a streamed `index.html` on the Drive (`GET` + `PATCH /SASjsApi/drive/file`).
+
+Gotchas:
+
+- The packaged binaries (`api-linux` etc.) reject some globally-exported `NODE_OPTIONS` (e.g. `--network-family-autoselection`) — start with `NODE_OPTIONS="" ./api-linux`.
+- AppStream URLs redirect to a trailing slash (`/AppStream/MyApp` → 301 → `/AppStream/MyApp/`) — test/automation scripts should use the trailing-slash URL directly.

AGENTS.md

@@ -24,6 +24,7 @@ This repo is the SASjs Macro Core library — a collection of MIT-licensed, prod
 - One macro per file; filename must match macro name.
 - Macro *calls* should NOT be terminated with a semicolon. Use `%my_macro()` not `%my_macro();`.
 - Macro variables must always be local, to prevent scope leakage.
+- Always use `mf_getuniquefileref` when assigning filerefs (never hardcode or hand-roll unique filerefs).
 
 
 ## Testing

README.md

@@ -228,7 +228,7 @@ We are currently on major release v5.  The following breaking changes were appli
 * mp_abort.sas - the redundant type= parameter was removed.
 * mp_coretable.sas - removed, and replaced by the standalone macros in the `ddl` folder
 * mp_getddl.sas - renamed to mp_ds2ddl.sas (consistent with other ds2xxx macros).  The default for SHOWLOG is now YES instead of NO.
-* mp_testservice.sas - renamed to mp_execute.sas (as it doesn't actually test anything)
+* mp_testservice.sas - renamed to mx_execute.sas (as it doesn't actually test anything, and the mp_ suite should not reference mx_ macros)
 
 ## Star Gazing