fauxnix-cli 0.11.0 → 0.12.0

package/dist/commands/sysinfo.js

@@ -1,6 +1,6 @@
 import { FauxnixParseError, isUnquotedLiteral, wordToString } from '../ast.js';
-import { lookup, parseWords, psStr, registeredNames } from '../registry.js';
-import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, varExtraOf, arithExpr, setArithHelperPreamble, isSpecialShellVar, } from '../translator.js';
+import { lookup, parseWords, psErr, psStr, registeredNames } from '../registry.js';
+import { argListExpr, exprOfWord, literalOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, varExtraOf, arithExpr, setArithHelperPreamble, isSpecialShellVar, EXECUTE_TRANSLATION, PURE_TRANSLATION, } from '../translator.js';
 import { handlers as textIoHandlers } from './text-io.js';
 /* ------------------------------------------------------------------ */
 /* Shared TS helpers                                                   */
@@ -62,6 +62,32 @@ function splitAssignWord(w) {
     }
     return null;
 }
+/** Remove an unquoted literal option prefix while preserving dynamic Word parts. */
+function wordAfterPrefix(w, prefix) {
+    let remaining = prefix;
+    const out = [];
+    for (const part of w) {
+        if (remaining === '') {
+            out.push(part);
+            continue;
+        }
+        if (part.kind !== 'Text')
+            return null;
+        if (remaining.startsWith(part.text)) {
+            remaining = remaining.slice(part.text.length);
+            continue;
+        }
+        if (part.text.startsWith(remaining)) {
+            const tail = part.text.slice(remaining.length);
+            if (tail !== '')
+                out.push({ kind: 'Text', text: tail });
+            remaining = '';
+            continue;
+        }
+        return null;
+    }
+    return remaining === '' ? out : null;
+}
 /** Text Words -> PS array expression. */
 function textArgs(words) {
     return argListExpr(words, exprOfWord);
@@ -97,10 +123,10 @@ const PS_WHICH_FN = [
     "  foreach ($fx_d in ($env:PATH -split ';')) {",
     "    if ($fx_d -eq '') { continue }",
     '    $fx_c = Join-Path $fx_d $n',
-    '    if (Test-Path -LiteralPath $fx_c) { return $fx_c }',
+    '    if (Test-Path -LiteralPath $fx_c -PathType Leaf) { return $fx_c }',
     "    $fx_exts = @(($env:PATHEXT -split ';') + '.exe') | Select-Object -Unique",
     '    foreach ($fx_e in $fx_exts) {',
-    '      if (Test-Path -LiteralPath ($fx_c + $fx_e)) { return ($fx_c + $fx_e) }',
+    '      if (Test-Path -LiteralPath ($fx_c + $fx_e) -PathType Leaf) { return ($fx_c + $fx_e) }',
     '    }',
     '  }',
     "  return ''",
@@ -112,23 +138,24 @@ const PS_MON_FN = "function fx-mon($m) { return @('Jan','Feb','Mar','Apr','May',
 /* cd / pwd                                                            */
 /* ------------------------------------------------------------------ */
 const cd = (args) => {
-    if (args.length === 0) {
+    const { operandWords } = parseWords(args);
+    if (operandWords.length === 0) {
         return [
             'try { Set-Location -LiteralPath $HOME }',
             "catch { [Console]::Error.WriteLine('bash: cd: ' + $_.Exception.Message); $script:fx_exit = 1 }",
         ].join('\n');
     }
-    if (args.length > 1) {
+    if (operandWords.length > 1) {
         return "[Console]::Error.WriteLine('bash: cd: too many arguments'); $script:fx_exit = 1";
     }
-    if (wordToString(args[0]) === '-') {
+    if (wordToString(operandWords[0]) === '-') {
         return [
             "if (-not $env:FAUXNIX_OLDPWD) { [Console]::Error.WriteLine('bash: cd: OLDPWD not set'); $script:fx_exit = 1 }",
             'else { try { Set-Location -LiteralPath $env:FAUXNIX_OLDPWD } catch { [Console]::Error.WriteLine("bash: cd: " + $env:FAUXNIX_OLDPWD + ": No such file or directory"); $script:fx_exit = 1 } }',
         ].join('\n');
     }
     return [
-        '$fx_ds = ' + argListExpr([args[0]]),
+        '$fx_ds = ' + argListExpr([operandWords[0]]),
         "if ($fx_ds.Count -ne 1) { [Console]::Error.WriteLine('bash: cd: too many arguments'); $script:fx_exit = 1 }",
         'else { $fx_d = [string]$fx_ds[0]',
         'if (-not (Test-Path -LiteralPath $fx_d)) { [Console]::Error.WriteLine("bash: cd: " + $fx_d + ": No such file or directory"); $script:fx_exit = 1 }',
@@ -137,7 +164,10 @@ const cd = (args) => {
     ].join('\n');
 };
 const pwd = (args) => {
-    void args; // -P accepted; physical == logical for Windows providers
+    const { operandWords } = parseWords(args);
+    if (operandWords.length > 0)
+        return psErr('pwd', "extra operand '" + wordToString(operandWords[0]) + "'. Try 'pwd --help'.");
+    // -L is the default. CommandSpec rejects -P because junctions make it distinct.
     return "(Get-Location).Path.Replace('\\', '/')";
 };
 /* ------------------------------------------------------------------ */
@@ -150,8 +180,10 @@ const exportCmd = (args) => {
     const sets = [];
     for (const w of args) {
         const t = wordToString(w);
+        if (t === '-')
+            return psErr('export', "invalid option '-'. Try 'export --help'.");
         if (t.startsWith('-'))
-            continue; // -n / -f accepted and ignored
+            continue; // validated by CommandSpec
         const sp = splitAssignWord(w);
         if (sp === null)
             continue; // `export VAR` (bare name) -> no-op success
@@ -202,31 +234,68 @@ const env = (args, ctx) => {
     const unsets = [];
     let i = 0;
     let cmdIdx = -1;
-    while (i < raw.length) {
-        const t = raw[i];
-        if (t === '--') {
-            cmdIdx = i + 1;
-            break;
-        }
-        if (t === '-i' || t === '--ignore-environment') {
+    let optionsDone = false;
+    const addUnset = (word) => {
+        const name = word ? literalOfWord(word) : null;
+        if (name === null || !NAME_RE.test(name)) {
             return ('[Console]::Error.WriteLine(' +
-                psStr('fauxnix: env -i/--ignore-environment is not supported (would silently keep inherited secrets). Use env -u NAME or unset first instead.') +
-                '); $script:fx_exit = 2');
-        }
-        if (t === '-u' || t === '--unset') {
-            if (i + 1 < raw.length)
-                unsets.push(raw[i + 1]);
-            i += 2;
-            continue;
-        }
-        if (t.startsWith('-u=') || t.startsWith('--unset=')) {
-            unsets.push(t.slice(t.indexOf('=') + 1));
-            i++;
-            continue;
+                psStr('env: -u/--unset requires a literal variable name in fauxnix; expand and unset the name in a separate command instead') +
+                '); $script:fx_exit = 125');
         }
-        if (t.startsWith('-')) {
-            i++; // unknown flags ignored
-            continue;
+        unsets.push(name);
+        return null;
+    };
+    while (i < raw.length) {
+        const t = raw[i];
+        if (!optionsDone) {
+            if (t === '-') {
+                return ('[Console]::Error.WriteLine(' +
+                    psStr('env: option - (ignore environment) is not supported by fauxnix; use env -u NAME or unset first') +
+                    '); $script:fx_exit = 125');
+            }
+            if (t === '--') {
+                optionsDone = true;
+                i++;
+                continue;
+            }
+            if (t === '-i' || t === '--ignore-environment') {
+                return ('[Console]::Error.WriteLine(' +
+                    psStr('fauxnix: env -i/--ignore-environment is not supported (would silently keep inherited secrets). Use env -u NAME or unset first instead.') +
+                    '); $script:fx_exit = 2');
+            }
+            if (t === '-u' || t === '--unset') {
+                const err = addUnset(args[i + 1]);
+                if (err)
+                    return err;
+                i += 2;
+                continue;
+            }
+            if (t.startsWith('-u=')) {
+                const err = addUnset(wordAfterPrefix(args[i], '-u=') ?? undefined);
+                if (err)
+                    return err;
+                i++;
+                continue;
+            }
+            if (t.startsWith('--unset=')) {
+                const err = addUnset(wordAfterPrefix(args[i], '--unset=') ?? undefined);
+                if (err)
+                    return err;
+                i++;
+                continue;
+            }
+            if (t.startsWith('-u') && t.length > 2) {
+                const err = addUnset(wordAfterPrefix(args[i], '-u') ?? undefined);
+                if (err)
+                    return err;
+                i++;
+                continue;
+            }
+            if (t.startsWith('-')) {
+                i++; // unknown flags are rejected by CommandSpec
+                continue;
+            }
+            optionsDone = true;
         }
         const sp = splitAssignWord(args[i]);
         if (sp !== null && NAME_RE.test(sp.name)) {
@@ -240,7 +309,7 @@ const env = (args, ctx) => {
     const lines = [];
     if (cmdIdx >= 0 && cmdIdx < args.length) {
         const cmdWords = args.slice(cmdIdx);
-        lines.push(translateSimple({ kind: 'SimpleCommand', assignments: [], name: cmdWords[0], args: cmdWords.slice(1), redirects: [] }, ctx.position, ctx.hasStdin));
+        lines.push(translateSimple({ kind: 'SimpleCommand', assignments: [], name: cmdWords[0], args: cmdWords.slice(1), redirects: [] }, ctx.position, ctx.hasStdin, ctx.translationMode === 'pure' ? PURE_TRANSLATION : EXECUTE_TRANSLATION));
     }
     else {
         lines.push(ENV_LIST_PS);
@@ -249,7 +318,7 @@ const env = (args, ctx) => {
     return wrapTempEnv(sets, lines.join('\n'), { unsets });
 };
 const printenv = (args) => {
-    const names = stripFlags(args);
+    const { operandWords: names } = parseWords(args);
     if (names.length === 0)
         return ENV_LIST_PS;
     return [
@@ -264,11 +333,12 @@ const printenv = (args) => {
 /* ps                                                                  */
 /* ------------------------------------------------------------------ */
 const ps = (args) => {
-    const raw = args.map(wordToString);
     const { flags, operandWords } = parseWords(args);
-    const full = operandWords.some((w) => wordToString(w) === 'aux') ||
-        (flags.has('e') && flags.has('f')) ||
-        raw.includes('-ef');
+    const badOperand = operandWords.find((w) => wordToString(w) !== 'aux');
+    if (badOperand) {
+        return psErr('ps', "unsupported operand '" + wordToString(badOperand) + "'. Use 'ps', 'ps -ef', or 'ps aux'.");
+    }
+    const full = operandWords.some((w) => wordToString(w) === 'aux') || flags.has('f');
     if (full) {
         return [
             PS_MON_FN,
@@ -516,7 +586,7 @@ const sleep = (args) => {
 const which = (args) => {
     const ws = stripFlags(args);
     if (ws.length === 0)
-        return '';
+        return psErr('which', "missing command name. Try 'which --help'.");
     return [
         PS_WHICH_FN,
         '$fx_b = @(' + builtinNames().map(psStr).join(', ') + ')',
@@ -529,7 +599,7 @@ const which = (args) => {
     ].join('\n');
 };
 const type = (args) => {
-    const ws = stripFlags(args);
+    const { operandWords: ws } = parseWords(args);
     if (ws.length === 0)
         return '';
     return [
@@ -549,11 +619,16 @@ const type = (args) => {
 /** `command -v name` (and bare `command name args` as a no-alias run). */
 const commandCmd = (args, ctx) => {
     let i = 0;
-    let identify = false;
+    let identify = null;
     while (i < args.length) {
         const t = wordToString(args[i]);
-        if (t === '-v' || t === '-V') {
-            identify = true;
+        if (t === '-v') {
+            identify = 'path';
+            i++;
+            continue;
+        }
+        if (t === '-V') {
+            identify = 'verbose';
             i++;
             continue;
         }
@@ -561,14 +636,14 @@ const commandCmd = (args, ctx) => {
             i++;
             break;
         }
-        if (t.startsWith('-')) {
+        if (t.startsWith('-') && t !== '-') {
             i++;
             continue;
         }
         break;
     }
     const rest = args.slice(i);
-    if (identify) {
+    if (identify !== null) {
         if (rest.length === 0)
             return '';
         return [
@@ -576,11 +651,15 @@ const commandCmd = (args, ctx) => {
             '$fx_b = @(' + builtinNames().map(psStr).join(', ') + ')',
             '$fx_ns = ' + textArgs(rest),
             'foreach ($fx_n in $fx_ns) {',
-            "  if ($fx_b -contains $fx_n) { '/usr/bin/' + $fx_n }",
+            identify === 'verbose'
+                ? "  if ($fx_b -contains $fx_n) { $fx_n + ' is /usr/bin/' + $fx_n }"
+                : "  if ($fx_b -contains $fx_n) { '/usr/bin/' + $fx_n }",
             '  else {',
             '    $fx_w = fx-which $fx_n',
             "    if ($fx_w -eq '') { $script:fx_exit = 1 }",
-            "    else { $fx_w.Replace('\\', '/') }",
+            identify === 'verbose'
+                ? "    else { $fx_n + ' is ' + $fx_w.Replace('\\', '/') }"
+                : "    else { $fx_w.Replace('\\', '/') }",
             '  }',
             '}',
         ].join('\n');
@@ -593,15 +672,28 @@ const commandCmd = (args, ctx) => {
         name: rest[0],
         args: rest.slice(1),
         redirects: [],
-    }, ctx.position, ctx.hasStdin);
+    }, ctx.position, ctx.hasStdin, ctx.translationMode === 'pure' ? PURE_TRANSLATION : EXECUTE_TRANSLATION);
 };
 /* ------------------------------------------------------------------ */
 /* whoami / id / groups                                                */
 /* ------------------------------------------------------------------ */
-const whoami = () => '$env:USERNAME.ToLower()';
+const whoami = (args) => {
+    const { operandWords } = parseWords(args);
+    if (operandWords.length > 0)
+        return psErr('whoami', "extra operand '" + wordToString(operandWords[0]) + "'. Try 'whoami --help'.");
+    return '$env:USERNAME.ToLower()';
+};
 const id = (args) => {
-    const { flags } = parseWords(args);
-    const wantNum = flags.has('u') || flags.has('g') || flags.has('G');
+    const { flags, operandWords } = parseWords(args);
+    if (operandWords.length > 0) {
+        return psErr('id', 'user operands are not supported; omit USER to inspect the current account');
+    }
+    const selectors = ['u', 'g', 'G'].filter((flag) => flags.has(flag));
+    if (selectors.length > 1)
+        return psErr('id', 'cannot print multiple ID selectors together');
+    if (flags.has('n') && selectors.length === 0)
+        return psErr('id', "option '-n' requires -u or -g");
+    const wantNum = selectors.length === 1;
     const wantName = flags.has('n');
     const uidPs = [
         '$fx_sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value',
@@ -616,7 +708,11 @@ const id = (args) => {
         "'uid=' + $fx_uid + '(' + $env:USERNAME + ') gid=' + $fx_uid + '(' + $env:USERNAME + ') groups=' + $fx_uid + '(' + $env:USERNAME + ')'",
     ].join('\n');
 };
-const groups = () => {
+const groups = (args) => {
+    const { operandWords } = parseWords(args);
+    if (operandWords.length > 0) {
+        return psErr('groups', 'user operands are not supported; omit USER to inspect the current account');
+    }
     return [
         '$fx_id = [System.Security.Principal.WindowsIdentity]::GetCurrent()',
         '$fx_gs = @()',
@@ -699,8 +795,8 @@ const DATE_FNS = [
     '}',
 ].join('\n');
 const date = (args) => {
-    const { flags, operandWords } = parseWords(args, ['d']);
-    const utc = flags.has('u');
+    const { flags, longs, operandWords } = parseWords(args, ['d'], ['--date']);
+    const utc = flags.has('u') || longs.has('--utc');
     // find the -d value as a Word (so dynamic values stay PS expressions)
     const raw = args.map(wordToString);
     let dWord = null;
@@ -709,15 +805,34 @@ const date = (args) => {
             dWord = args[k + 1] ?? null;
             break;
         }
+        if (raw[k].startsWith('--date=')) {
+            dWord = wordAfterPrefix(args[k], '--date=');
+            break;
+        }
+        if (raw[k].startsWith('-') && !raw[k].startsWith('--')) {
+            const body = raw[k].slice(1);
+            const dIndex = body.indexOf('d');
+            if (dIndex >= 0) {
+                const prefix = '-' + body.slice(0, dIndex + 1);
+                const attached = wordAfterPrefix(args[k], prefix);
+                dWord = attached && attached.length > 0 ? attached : (args[k + 1] ?? null);
+                break;
+            }
+        }
+    }
+    const fmtWords = operandWords.filter((w) => wordToString(w).startsWith('+'));
+    const badOperand = operandWords.find((w) => !wordToString(w).startsWith('+'));
+    if (badOperand || fmtWords.length > 1) {
+        return psErr('date', "extra operand '" + wordToString(badOperand ?? fmtWords[1]) + "'. Try 'date --help'.");
     }
-    const fmtWord = operandWords.find((w) => wordToString(w).startsWith('+'));
+    const fmtWord = fmtWords[0];
     const lines = [DATE_FNS];
     lines.push('$fx_d = ' + (utc ? '[DateTime]::UtcNow' : 'Get-Date'));
     lines.push('$fx_ok = $true');
     if (dWord !== null) {
         lines.push('$fx_ds = ' + exprOfWord(dWord));
         lines.push("if ($fx_ds -like '@*') {");
-        lines.push("  try { $fx_n = [long]($fx_ds.Substring(1)); $fx_d = ([datetime]'1970-01-01').AddSeconds($fx_n)" +
+        lines.push("  try { $fx_n = [long]($fx_ds.Substring(1)); $fx_epoch = [DateTime]::SpecifyKind([datetime]'1970-01-01', [DateTimeKind]::Utc); $fx_d = $fx_epoch.AddSeconds($fx_n)" +
             (utc ? ' }' : '.ToLocalTime() }'));
         lines.push('  catch { $fx_ok = $false }');
         lines.push('} else { $fx_ok = $false }');
@@ -740,31 +855,43 @@ const date = (args) => {
 /* ------------------------------------------------------------------ */
 const ARCH_PS = "($(if ($env:PROCESSOR_ARCHITECTURE -like 'ARM*') { 'ARM64' } else { 'x86_64' }))";
 const uname = (args) => {
-    const { flags } = parseWords(args);
-    if (flags.has('a')) {
+    const { flags, longs, operandWords } = parseWords(args);
+    if (operandWords.length > 0)
+        return psErr('uname', "extra operand '" + wordToString(operandWords[0]) + "'. Try 'uname --help'.");
+    const has = (short, long) => flags.has(short) || longs.has(long);
+    if (has('a', '--all')) {
         return ("('Linux ' + $env:COMPUTERNAME + ' 6.8.0-fauxnix #1 SMP PREEMPT_DYNAMIC ' + " +
             ARCH_PS +
             " + ' GNU/Linux')");
     }
     const parts = [];
-    if (flags.has('s') || flags.size === 0)
+    if (has('s', '--kernel-name') || (flags.size === 0 && longs.size === 0))
         parts.push("'Linux'");
-    if (flags.has('n'))
+    if (has('n', '--nodename'))
         parts.push('$env:COMPUTERNAME');
-    if (flags.has('r'))
+    if (has('r', '--kernel-release'))
         parts.push("'6.8.0-fauxnix'");
-    if (flags.has('v'))
+    if (has('v', '--kernel-version'))
         parts.push("'#1 SMP PREEMPT_DYNAMIC'");
-    if (flags.has('m') || flags.has('p'))
+    if (has('m', '--machine') || has('p', '--processor'))
         parts.push(ARCH_PS);
-    if (flags.has('o'))
+    if (has('o', '--operating-system'))
         parts.push("'GNU/Linux'");
     if (parts.length === 0)
         parts.push("'Linux'");
     return '(@(' + parts.join(', ') + ") -join ' ')";
 };
-const hostname = () => '$env:COMPUTERNAME';
-const uptime = () => {
+const hostname = (args) => {
+    const { operandWords } = parseWords(args);
+    if (operandWords.length > 0) {
+        return psErr('hostname', 'setting or selecting a host is not supported; omit operands to print the current hostname');
+    }
+    return '$env:COMPUTERNAME';
+};
+const uptime = (args) => {
+    const { operandWords } = parseWords(args);
+    if (operandWords.length > 0)
+        return psErr('uptime', "extra operand '" + wordToString(operandWords[0]) + "'. Try 'uptime --help'.");
     return [
         '$fx_now = Get-Date',
         '$fx_os = Get-CimInstance Win32_OperatingSystem',
@@ -777,8 +904,49 @@ const uptime = () => {
     ].join('\n');
 };
 const free = (args) => {
-    const { flags } = parseWords(args);
-    const unit = flags.has('h') ? 'h' : flags.has('g') ? 'g' : flags.has('m') ? 'm' : 'k';
+    const { flags, longs, operandWords } = parseWords(args);
+    if (operandWords.length > 0)
+        return psErr('free', "extra operand '" + wordToString(operandWords[0]) + "'. Try 'free --help'.");
+    void flags;
+    void longs;
+    let unit = 'k';
+    let sawHuman = false;
+    let nonHumanUnits = 0;
+    for (const raw of args.map(wordToString)) {
+        if (raw === '--human') {
+            unit = 'h';
+            sawHuman = true;
+        }
+        else if (raw === '--gibi') {
+            unit = 'g';
+            nonHumanUnits++;
+        }
+        else if (raw === '--mebi') {
+            unit = 'm';
+            nonHumanUnits++;
+        }
+        else if (raw === '--kibi') {
+            unit = 'k';
+            nonHumanUnits++;
+        }
+        else if (raw.startsWith('-') && !raw.startsWith('--')) {
+            for (const flag of raw.slice(1)) {
+                if (flag === 'h') {
+                    unit = 'h';
+                    sawHuman = true;
+                }
+                else if (flag === 'g' || flag === 'm' || flag === 'k') {
+                    unit = flag;
+                    nonHumanUnits++;
+                }
+            }
+        }
+    }
+    if (!sawHuman && nonHumanUnits > 1) {
+        return psErr('free', 'multiple unit options are not supported together; choose one of -k, -m, or -g');
+    }
+    if (sawHuman)
+        unit = 'h';
     // value converter for KB-based memory values
     let conv;
     if (unit === 'k')
@@ -819,11 +987,20 @@ const free = (args) => {
         ").TrimEnd()");
     return lines.join('\n');
 };
-const nproc = () => '[string][Environment]::ProcessorCount';
+const nproc = (args) => {
+    const { operandWords } = parseWords(args);
+    if (operandWords.length > 0)
+        return psErr('nproc', "extra operand '" + wordToString(operandWords[0]) + "'. Try 'nproc --help'.");
+    return '[string][Environment]::ProcessorCount';
+};
 /* ------------------------------------------------------------------ */
 /* clear / true / false / :                                            */
 /* ------------------------------------------------------------------ */
-const clear = () => "([char]27 + '[2J' + [char]27 + '[H')";
+const clear = (args) => {
+    if (args.length > 0)
+        return psErr('clear', "extra operand '" + wordToString(args[0]) + "'. Try 'clear --help'.");
+    return "([char]27 + '[2J' + [char]27 + '[H')";
+};
 const trueCmd = () => '';
 const falseCmd = () => '$script:fx_exit = 1';
 const colon = () => '';
@@ -2329,7 +2506,7 @@ const timeout = (args, ctx) => {
         return "[Console]::Error.WriteLine('timeout: missing operand'); $script:fx_exit = 125";
     }
     // NOTE: stdin is not forwarded into the job — documented limitation.
-    const inner = translateSimple({ kind: 'SimpleCommand', assignments: [], name: cmdWords[0], args: cmdWords.slice(1), redirects: [] }, ctx.position, false);
+    const inner = translateSimple({ kind: 'SimpleCommand', assignments: [], name: cmdWords[0], args: cmdWords.slice(1), redirects: [] }, ctx.position, false, ctx.translationMode === 'pure' ? PURE_TRANSLATION : EXECUTE_TRANSLATION);
     const innerLines = inner.split('\n').map((l) => (l ? '    ' + l : l));
     return [
         '$fx_tn = ' + exprOfWord(nWord),
@@ -2570,6 +2747,321 @@ const shiftCmd = (args) => {
     ].join('\n');
 };
 /* ------------------------------------------------------------------ */
+export const specs = [
+    {
+        names: ['cd'],
+        options: [
+            { short: 'L', support: 'implemented' },
+            { short: 'P', support: 'unsupported', reason: 'physical symlink/junction resolution' },
+            { short: 'e', support: 'unsupported', reason: 'physical-resolution failure mode' },
+            { short: '@', support: 'unsupported', reason: 'extended-attribute directory view' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: cd,
+    },
+    {
+        names: ['pwd'],
+        options: [
+            { short: 'L', support: 'implemented' },
+            { short: 'P', support: 'unsupported', reason: 'physical symlink/junction resolution' },
+            { short: 'W', support: 'unsupported', reason: 'MSYS Windows-path output' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: pwd,
+    },
+    {
+        names: ['export'],
+        options: [
+            { short: 'f', support: 'unsupported', reason: 'shell functions are not supported' },
+            { short: 'n', support: 'unsupported', reason: 'all fauxnix variables live in the session environment' },
+            { short: 'p', support: 'unsupported', reason: 'declare-style shell output' },
+        ],
+        effects: ['read', 'write'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: exportCmd,
+    },
+    {
+        names: ['unset'],
+        options: [
+            { short: 'v', support: 'implemented' },
+            { short: 'f', support: 'unsupported', reason: 'shell functions are not supported' },
+            { short: 'n', support: 'unsupported', reason: 'nameref variables are not supported' },
+        ],
+        effects: ['write'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: unset,
+    },
+    {
+        names: ['env'],
+        options: [
+            {
+                short: 'u',
+                long: '--unset',
+                takesValue: true,
+                support: 'implemented',
+                reason: 'literal variable names only',
+            },
+            {
+                short: 'i',
+                long: '--ignore-environment',
+                support: 'unsupported',
+                reason: 'would silently keep inherited secrets; use env -u NAME or unset first',
+            },
+            { short: '0', long: '--null', support: 'unsupported', reason: 'NUL-terminated output' },
+            { short: 'C', long: '--chdir', takesValue: true, support: 'unsupported', reason: 'temporary working directory' },
+            { short: 'S', long: '--split-string', takesValue: true, support: 'unsupported', reason: 'shell-like string splitting' },
+        ],
+        effects: ['process'],
+        platform: 'windows-ps51',
+        dispatch: 'dynamic',
+        usageExit: 125,
+        leadingOptions: true,
+        handler: env,
+    },
+    {
+        names: ['printenv'],
+        options: [
+            { short: '0', long: '--null', support: 'unsupported', reason: 'NUL-terminated output' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: printenv,
+    },
+    {
+        names: ['ps'],
+        options: [
+            { short: 'e', long: '--everyone', support: 'implemented' },
+            { short: 'A', long: '--all', support: 'implemented' },
+            { short: 'f', support: 'implemented' },
+            { short: 'a', support: 'unsupported', reason: 'terminal-based process selection' },
+            { short: 'x', support: 'unsupported', reason: 'terminal-based process selection' },
+            { short: 'u', support: 'unsupported', reason: 'BSD user-oriented format' },
+            { long: '--user', takesValue: true, support: 'unsupported', reason: 'user filtering' },
+            { short: 'p', long: '--pid', takesValue: true, support: 'unsupported', reason: 'PID filtering' },
+            { short: 'o', long: '--format', takesValue: true, support: 'unsupported', reason: 'custom output columns' },
+            { long: '--sort', takesValue: true, support: 'unsupported', reason: 'custom process ordering' },
+        ],
+        effects: ['process'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: ps,
+    },
+    {
+        names: ['sleep'],
+        options: [],
+        effects: ['process'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: sleep,
+    },
+    {
+        names: ['which'],
+        options: [
+            { short: 'a', long: '--all', support: 'unsupported', reason: 'all matching PATH entries' },
+            { short: 's', support: 'unsupported', reason: 'silent status-only mode' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: which,
+    },
+    {
+        names: ['type'],
+        options: [
+            { short: 'a', support: 'unsupported', reason: 'all matching definitions' },
+            { short: 'f', support: 'unsupported', reason: 'shell functions are not supported' },
+            { short: 'P', support: 'unsupported', reason: 'forced PATH lookup' },
+            { short: 'p', support: 'unsupported', reason: 'PATH-only lookup' },
+            { short: 't', support: 'unsupported', reason: 'type-name-only output' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: type,
+    },
+    {
+        names: ['command'],
+        options: [
+            { short: 'v', support: 'implemented' },
+            { short: 'V', support: 'implemented' },
+            { short: 'p', support: 'unsupported', reason: 'guaranteed default utility PATH' },
+        ],
+        effects: ['process'],
+        platform: 'windows-ps51',
+        dispatch: 'dynamic',
+        usageExit: 2,
+        leadingOptions: true,
+        handler: commandCmd,
+    },
+    {
+        names: ['whoami'],
+        options: [],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: whoami,
+    },
+    {
+        names: ['id'],
+        options: [
+            { short: 'u', support: 'implemented' },
+            { short: 'g', support: 'implemented' },
+            { short: 'n', support: 'implemented' },
+            { short: 'G', support: 'unsupported', reason: 'supplementary group ID mapping' },
+            { short: 'r', support: 'unsupported', reason: 'real versus effective IDs' },
+            { short: 'z', support: 'unsupported', reason: 'NUL-terminated output' },
+            { short: 'Z', support: 'unsupported', reason: 'SELinux security context' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: id,
+    },
+    {
+        names: ['groups'],
+        options: [],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: groups,
+    },
+    {
+        names: ['date'],
+        options: [
+            { short: 'u', long: '--utc', support: 'implemented' },
+            {
+                short: 'd',
+                long: '--date',
+                takesValue: true,
+                support: 'implemented',
+                reason: '@SECONDS input only',
+            },
+            { short: 'I', long: '--iso-8601', support: 'unsupported', reason: 'ISO precision selection' },
+            { short: 'R', long: '--rfc-email', support: 'unsupported', reason: 'RFC email formatting' },
+            { long: '--rfc-3339', takesValue: true, support: 'unsupported', reason: 'RFC 3339 precision selection' },
+            { short: 'r', long: '--reference', takesValue: true, support: 'unsupported', reason: 'file timestamp lookup' },
+            { short: 's', long: '--set', takesValue: true, support: 'unsupported', reason: 'changing the system clock' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: date,
+    },
+    {
+        names: ['uname'],
+        options: [
+            { short: 'a', long: '--all', support: 'implemented' },
+            { short: 's', long: '--kernel-name', support: 'implemented' },
+            { short: 'n', long: '--nodename', support: 'implemented' },
+            { short: 'r', long: '--kernel-release', support: 'implemented' },
+            { short: 'v', long: '--kernel-version', support: 'implemented' },
+            { short: 'm', long: '--machine', support: 'implemented' },
+            { short: 'p', long: '--processor', support: 'implemented' },
+            { short: 'o', long: '--operating-system', support: 'implemented' },
+            { short: 'i', long: '--hardware-platform', support: 'unsupported', reason: 'hardware-platform distinction' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: uname,
+    },
+    {
+        names: ['hostname'],
+        options: [
+            { short: 's', long: '--short', support: 'unsupported', reason: 'short-name selection' },
+            { short: 'f', long: '--fqdn', support: 'unsupported', reason: 'FQDN lookup' },
+            { short: 'd', long: '--domain', support: 'unsupported', reason: 'DNS domain lookup' },
+            { short: 'i', long: '--ip-address', support: 'unsupported', reason: 'address lookup' },
+            { short: 'I', long: '--all-ip-addresses', support: 'unsupported', reason: 'all-address lookup' },
+            { short: 'F', long: '--file', takesValue: true, support: 'unsupported', reason: 'changing the hostname from a file' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: hostname,
+    },
+    {
+        names: ['uptime'],
+        options: [
+            { short: 'p', long: '--pretty', support: 'unsupported', reason: 'pretty duration output' },
+            { short: 's', long: '--since', support: 'unsupported', reason: 'boot timestamp output' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: uptime,
+    },
+    {
+        names: ['free'],
+        options: [
+            { short: 'h', long: '--human', support: 'implemented' },
+            { short: 'k', long: '--kibi', support: 'implemented' },
+            { short: 'm', long: '--mebi', support: 'implemented' },
+            { short: 'g', long: '--gibi', support: 'implemented' },
+            { short: 'b', long: '--bytes', support: 'unsupported', reason: 'byte-unit output' },
+            { long: '--si', support: 'unsupported', reason: 'powers-of-1000 units' },
+            { short: 't', long: '--total', support: 'unsupported', reason: 'total row' },
+            { short: 'w', long: '--wide', support: 'unsupported', reason: 'wide buffer/cache columns' },
+            { short: 's', long: '--seconds', takesValue: true, support: 'unsupported', reason: 'repeating output' },
+            { short: 'c', long: '--count', takesValue: true, support: 'unsupported', reason: 'repeating output' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: free,
+    },
+    {
+        names: ['nproc'],
+        options: [
+            { long: '--all', support: 'unsupported', reason: 'installed versus available processor distinction' },
+            { long: '--ignore', takesValue: true, support: 'unsupported', reason: 'processor-count subtraction' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: nproc,
+    },
+    {
+        names: ['clear'],
+        options: [
+            { short: 'x', support: 'unsupported', reason: 'scrollback-preserving terminal control' },
+            { short: 'T', takesValue: true, support: 'unsupported', reason: 'alternate terminal type' },
+        ],
+        effects: [],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: clear,
+    },
+    {
+        names: ['timeout'],
+        options: [
+            { short: 's', long: '--signal', takesValue: true, support: 'unsupported', reason: 'signal selection' },
+            { short: 'k', long: '--kill-after', takesValue: true, support: 'unsupported', reason: 'two-phase termination' },
+            { long: '--preserve-status', support: 'unsupported', reason: 'child-status preservation after timeout' },
+            { long: '--foreground', support: 'unsupported', reason: 'interactive foreground process groups' },
+            { short: 'v', long: '--verbose', support: 'unsupported', reason: 'signal diagnostics' },
+        ],
+        effects: ['process'],
+        platform: 'windows-ps51',
+        dispatch: 'dynamic',
+        usageExit: 125,
+        leadingOptions: true,
+        handler: timeout,
+    },
+];
 export const handlers = {
     cd,
     pwd,