iagate-scriptkit

ScriptKit (iagate-scriptkit)

Build and transpile universal scripts to PowerShell (Windows) or Bash (macOS/Linux) using a portable program builder, DSLs, and platform-aware high-level APIs.

Install

npm install iagate-scriptkit

Core exports

• ScriptBuilder: imperative builder for shell scripts (ps1/sh) with run() helper
• PowerShellDsl, BashDsl, CSharpBuilder: structured DSLs for script/code generation
• UniversalTranspiler, UniversalProgramBuilder, detectPlatform
• ScriptQuery / scriptQuery(): fluent high-level builder
• universalApis and category-specific groups (fsApis, systemApis, processApis, etc.)

What you can do (summary)

• File system: ensure/mirror trees, copy/move/remove, pattern copy, search, compress/extract, hashes, chmod/chown, mktemp
• System: restart/shutdown/sleep/lock, open URL/terminal, system info, network interfaces
• Display/Audio: list display modes, set resolution/brightness; set volume, mute/unmute, TTS/beep
• Firewall: list/enable/disable/add/remove rules (per OS), default policies
• Processes: list/kill/start detached, top, CPU/mem usage, open files, uptime, GPU info
• Packages: install/uninstall/update/list/info across brew/choco/apt/dnf
• Services: start/stop/restart/status/enable/disable/logs
• Clipboard: set/get/clear/type
• Networking: Wi-Fi scan/connect, ipconfig/ifconfig, open-port check, route table, DNS flush, speed test, curl
• Apps: notify/open/reveal/screenshot/default browser
• Users/Groups: list/add/remove, group membership, whois/passwd
• Printers/Bluetooth/Docker/Kubernetes/Power/NetConfig/Archives/Logs/Utils: broad coverage
• Codegen DSLs: generate PowerShell/Bash/C# (structs/classes/interfaces/enums, DllImport)

API catalog (by category)

Below are representative calls (not exhaustive). All return a UniversalProgram which you can transpile and run.

• fsApis: ensureDir, ensureTree, mirror, copy, copyPattern, move, rm, searchFiles|Dirs|Any, gzipFile, untarGz, hashSha256|Md5, chmod, touch, du, df, which, mktemp
• systemApis: restart, shutdown, sleep, lock, openUrl, openTerminal, systemInfoJson, netInterfacesJson, ping, traceroute, dnsLookup, envGet|envSet, hostname
• displayApis: modesJson, setResolution, setBrightness
• audioApis: setVolume, mute, unmute, beep, say
• firewallApis: listJson, enableRule, disableRule, addAllowTcp|Udp, addDenyTcp|Udp, removeRule, blockAllInbound, allowAllOutbound
• processApis: list, killByPid|Name, startDetached, niceTop, cpuUsage, memUsage, openFile, uptime, gpuInfo
• packageApis: install, uninstall, updateAll, list, whichManager, addTap, cleanup, info
• serviceApis: start, stop, restart, status, enable, disable, list, logs
• clipboardApis: set, get, clear, typeText
• netApis: wifiScan, wifiConnect, ipConfig, openPortCheck, routeTable, dnsCacheFlush, speedTest, curl
• appApis: notify, open, defaultBrowser, openUrl, revealInFolder, screenshot
• userApis: currentUser, listUsers, addUser, deleteUser, listGroups, addGroup, deleteGroup, userAddToGroup, userRemoveFromGroup, whoIs, passwd
• printerApis: list, default, setDefault, pause, resume, status, printFile, jobs
• bluetoothApis: list, powerOn|Off, pair|connect|disconnect
• dockerApis: version, ps, images, start|stop|restart|rm, logs, run, pull
• k8sApis: contexts, setContext, getPods|Services|Nodes, logs, applyFile, portForward
• powerApis: batteryStatus, sleepDisplay, powerPlan, timeSync, timezoneGet|Set, hibernate, rebootToFirmware
• netConfigApis: proxySet|Unset|Get, vpnList|Connect|Disconnect, hostsAdd|List
• archiveApis: sevenZipCompress|Extract, rarExtract, zipList|Test, tarList|Test
• logApis: tail|follow|grep|head
• utilApis: uuid, base64Encode|Decode

Platform nuances are handled inside the transpiler; some calls may be best-effort on certain OSes.

Returns and execution model

• Transpile only:

  const program = fsApis.ensureDir('out')
  const { builder, shell } = UniversalTranspiler.transpile(program)
  // shell: 'powershell' on Windows, 'bash' otherwise
  

• Execute:

  const result = await builder.run()
  // result: { stdout: string; stderr: string }
  // or a ServiceResult if you pass a host Service implementation
  

Examples with expected outputs

Ensure directories and mirror content

import { UniversalTranspiler, fsApis as fs } from 'iagate-scriptkit'

const program = fs.ensureDirs(['out/logs', 'out/data'])
const { builder } = UniversalTranspiler.transpile(program)
const r1 = await builder.run()
// Expected: stdout empty or OS command acknowledgements; directories exist

const p2 = fs.copyPattern('src', 'out/data', '*.json', true)
const { builder: b2 } = UniversalTranspiler.transpile(p2)
const r2 = await b2.run()
// Expected: JSON files copied; stdout may contain command output depending on OS

Display modes JSON

import { UniversalTranspiler, displayApis as display } from 'iagate-scriptkit'

const { builder } = UniversalTranspiler.transpile(display.modesJson())
const out = await builder.run()
// Expected stdout (Windows example):
// [ { "resolution": "1920x1080", "width": 1920, "height": 1080, ... }, ... ]

Audio and notifications

import { UniversalTranspiler, audioApis as audio, appApis as app } from 'iagate-scriptkit'

await UniversalTranspiler.run(audio.setVolume(30))
await UniversalTranspiler.run(app.notify('Build', 'Finished'))
// Expected: volume set; native notification shown

Firewall allow TCP 5432 inbound

import { UniversalTranspiler, firewallApis as fw } from 'iagate-scriptkit'

const p = fw.addAllowTcp('db-allow-5432', 5432, 'in')
const { builder } = UniversalTranspiler.transpile(p)
const res = await builder.run()
// Expected: rule created (Windows: New-NetFirewallRule; Linux: ufw allow)

Docker and Kubernetes

import { UniversalTranspiler, dockerApis as d, k8sApis as k } from 'iagate-scriptkit'

await UniversalTranspiler.run(d.images())
await UniversalTranspiler.run(k.getPods('default'))
// Expected: stdout from docker/kubectl commands

scriptQuery fluent chain

import { scriptQuery } from 'iagate-scriptkit'

const { builder } = scriptQuery()
  .setEnv('NODE_ENV', 'production')
  .fs().ensureDir('build')
  .system().openUrl('https://example.com')
  .build()

const r = await builder.run()
// Expected: directory created; URL opened

PowerShell/Bash DSLs

PowerShellDsl highlights

• Control-flow: if/elseif/else/endif, try/catch/finally, for/foreach/while, switch, break/continue
• Data: var/set/inc, newArray/pushArray, newHash/addHash/setHashAtIndex, JSON: toJson/fromJson
• Utilities: ensureModule, ensureCommand, guard, retry, timeout, sleep, startProcess/stopProcess, ensureDir, registry/property helpers
• Parallelism: parallel(jobs: string[], ...) via background jobs and Receive-Job
• C# interop: addTypeFromCSharp to inline C# types and P/Invoke

Example (retry + parallel):

import { PowerShellDsl } from 'iagate-scriptkit'

const ps = new PowerShellDsl()
  .retry(3, 1000, p => p.startProcess('ping', ['-n','1','8.8.8.8']))
  .parallel([
    `Start-Sleep -Milliseconds 200; 'jobA'`,
    `Start-Sleep -Milliseconds 100; 'jobB'`,
  ], '$out', true, 2)
  .toJson('$out', 2)
  .build()
// Transpile then run; Expected: JSON array with job outputs

BashDsl highlights

• Control-flow: if/elif/else/fi, while, forIn
• Utilities: retry(times, delaySec), ensureCommand, guard, pipeline, command

Example:

import { BashDsl } from 'iagate-scriptkit'

const sh = new BashDsl()
  .retry(3, 1, s => s.command('curl', ['-fsSL', 'https://example.com']))
  .pipeline([`echo 'ok'`, `tr 'a-z' 'A-Z'`])
  .build()

CSharpBuilder (native codegen)

You can generate C# structures for P/Invoke or utility classes and inject them into PowerShell via Add-Type.

Supported:

• Structs with [StructLayout] and field attributes (MarshalAs)
• Classes with methods/properties/fields/constructors/static constructors
• Interfaces and Enums
• DllImport methods with CharSet, SetLastError
• Usings, namespace, generics, implements

Example: display settings interop (excerpt)

import { CSharpBuilder, PowerShellDsl } from 'iagate-scriptkit'

const cs = new CSharpBuilder()
  .struct('DEVMODE')
    .addFields([
      (f)=>f.type('string').named('dmDeviceName').attrs(['[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]']),
      { type: 'int', name: 'dmPelsWidth' },
      { type: 'int', name: 'dmPelsHeight' },
    ])
  .class('DisplaySettings')
    .addDllImportMethod('user32.dll', 'bool', 'EnumDisplaySettings', [
      { type: 'string', name: 'deviceName' },
      { type: 'int', name: 'modeNum' },
      { type: 'ref DEVMODE', name: 'devMode' },
    ])

const ps = new PowerShellDsl().addTypeFromCSharp(cs.build()).build()
// Expected: PowerShell can now call [DisplaySettings]::EnumDisplaySettings(...)

Notes

• builder.run() spawns platform commands; ensure required tools exist (brew/choco/apt/kubectl/docker/etc.).
• Some APIs are best-effort per OS; messages will indicate missing tools when applicable.
• To integrate with a host app, implement Service.executeWithTempFile and pass a Service to ScriptBuilder.run().

License

MIT