fauxnix-cli 0.9.3 → 0.12.0

package/dist/registry.js

@@ -154,6 +154,92 @@ export function parseWords(args, shortValues = [], longValues = []) {
     return { flags, longs, values, missingValue, operandWords };
 }
 const specs = new Map();
+/**
+ * C-5's curated agent-daily command set. Keep this explicit: a raw count of
+ * CommandSpecs is not enough to prove that the commands agents use every day
+ * are the ones protected by fail-loud option validation.
+ */
+export const AGENT_DAILY_60 = [
+    'basename',
+    'cat',
+    'cd',
+    'chmod',
+    'chown',
+    'clear',
+    'command',
+    'cp',
+    'cut',
+    'date',
+    'df',
+    'diff',
+    'dirname',
+    'du',
+    'echo',
+    'env',
+    'export',
+    'file',
+    'free',
+    'grep',
+    'groups',
+    'gunzip',
+    'gzip',
+    'head',
+    'hostname',
+    'id',
+    'll',
+    'ln',
+    'ls',
+    'mkdir',
+    'mktemp',
+    'mv',
+    'nproc',
+    'printenv',
+    'printf',
+    'ps',
+    'pwd',
+    'readlink',
+    'realpath',
+    'rm',
+    'rmdir',
+    'sleep',
+    'sort',
+    'stat',
+    'tail',
+    'tee',
+    'timeout',
+    'touch',
+    'tr',
+    'type',
+    'uname',
+    'uniq',
+    'unset',
+    'unzip',
+    'uptime',
+    'wc',
+    'which',
+    'whoami',
+    'zcat',
+    'zip',
+];
+/** Commands deliberately kept outside generic CommandSpec option walking. */
+export const COMMAND_SPEC_EXCLUSIONS = [
+    {
+        names: ['find'],
+        reason: 'option-looking predicates are parsed by the find expression compiler; generic short-option bundling would misread -name',
+    },
+    {
+        names: ['sed', 'awk'],
+        reason: 'program text and option grammar require command-specific parsing; any remaining unchecked options must be fixed there rather than treated as generic flags',
+    },
+    {
+        names: ['egrep'],
+        reason: 'semantic alias injects grep -E through its own handler; it must not be wrapped as an independent generic option parser',
+    },
+    {
+        names: ['tar'],
+        reason: 'argv is passed to Windows bsdtar; rejecting unlisted GNU/bsdtar options before native dispatch would reduce compatibility',
+    },
+];
 /** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */
 export function registerSpec(spec) {
     for (const name of spec.names) {
@@ -188,11 +274,30 @@ export function registeredSpecs() {
 }
 /** Markdown dump of every CommandSpec — source for docs/command-specs.md. */
 export function specsMarkdown() {
+    const dailySpecd = AGENT_DAILY_60.filter((name) => lookupSpec(name));
+    const dailyMissing = AGENT_DAILY_60.filter((name) => !lookupSpec(name));
     const lines = [
         '# Command specs',
         '',
         'Generated from `CommandSpec`. Unlisted commands still use unchecked `parseWords` (unknown flags ignored). Spec\'d commands fail loud on unknown or unsupported options.',
         '',
+        '## Agent-daily 60 (C-5)',
+        '',
+        'Curated command names: ' + AGENT_DAILY_60.map((name) => '`' + name + '`').join(', '),
+        '',
+        'Coverage: **' + dailySpecd.length + ' / ' + AGENT_DAILY_60.length + ' spec\'d**.',
+        '',
+        ...(dailyMissing.length
+            ? ['Missing specs: ' + dailyMissing.map((name) => '`' + name + '`').join(', '), '']
+            : []),
+        '## Intentional CommandSpec exclusions',
+        '',
+        'These commands stay outside the generic option walker by design. This is a structural rationale, not a claim that every command-specific option path is already strict.',
+        '',
+        '| Command | Rationale |',
+        '| --- | --- |',
+        ...COMMAND_SPEC_EXCLUSIONS.map((entry) => '| ' + entry.names.map((name) => '`' + name + '`').join(', ') + ' | ' + entry.reason + ' |'),
+        '',
     ];
     for (const spec of registeredSpecs()) {
         lines.push('## `' + spec.names.join('` / `') + '`');
@@ -296,7 +401,10 @@ export function specOptionError(spec, args, cmdName) {
             i++;
             continue;
         }
-        if (t.startsWith('-') && t.length > 1 && !/^-?\d/.test(t.slice(1, 2))) {
+        const firstShort = t.slice(1, 2);
+        if (t.startsWith('-') &&
+            t.length > 1 &&
+            (!/^\d$/.test(firstShort) || shorts.has(firstShort))) {
             const body = t.slice(1);
             for (let c = 0; c < body.length; c++) {
                 const ch = body[c];

package/dist/translator.d.ts

@@ -1,12 +1,42 @@
-import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, Word, WordPart } from './ast.js';
+import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, WhileCommand, CaseCommand, Word, WordPart } from './ast.js';
 import { PipelineCtx } from './registry.js';
+export interface TranslationContext {
+    /** `pure` renders a script without consulting command operands on disk. */
+    mode: 'execute' | 'pure';
+}
+export declare const EXECUTE_TRANSLATION: TranslationContext;
+export declare const PURE_TRANSLATION: TranslationContext;
+export declare const PURE_SED_FILE_MESSAGE = "fauxnix: translate does not read sed script files; use -e with the script text, or run the command to use -f";
 /** `${name:-word}` and friends using case-exact fx-scalar0. */
 export declare function paramExpr(name: string, op: ':-' | ':=' | ':+' | ':?' | '-' | '+' | '?', word: string): string;
+export declare function varExtraOf(p: WordPart): {
+    replace?: {
+        global: boolean;
+        pat: string;
+        repl: string;
+    };
+    slice?: {
+        offset: string;
+        length?: string;
+    };
+} | undefined;
 /** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
 export declare function varExpr(name: string, index?: string, param?: {
     op: ':-' | ':=' | ':+' | ':?' | '-' | '+' | '?';
     word: string;
-}, length?: boolean): string;
+}, length?: boolean, extra?: {
+    replace?: {
+        global: boolean;
+        pat: string;
+        repl: string;
+    };
+    slice?: {
+        offset: string;
+        length?: string;
+    };
+}): string;
+/** `$?` `$$` `$0`–`$n` `$#` `$@` `$*` — not ordinary `$env:` names. */
+export declare function isSpecialShellVar(name: string): boolean;
 /** Escape text destined for the inside of a PS double-quoted string. */
 export declare function escapeDq(s: string): string;
 /** Normalize a literal POSIX-ish path to its Windows equivalent. */
@@ -39,6 +69,7 @@ export declare function operandExpr(w: Word): string;
 /**
  * `${name[@]}` / `"pre${name[@]}post"` — one argv per element.
  * Unquoted `${name[*]}` also splats (bash); quoted `"${name[*]}"` stays one join.
+ * `$@` / unquoted `$*` splat like `${arr[@]}`; quoted `"$@"` still splats.
  */
 export declare function splatSpec(w: Word): {
     name: string;
@@ -53,9 +84,11 @@ export declare function argListExpr(words: Word[], fn?: (w: Word) => string): st
  * Unquoted command words join non-empty lines with a space (IFS
  * word-split approximation). Handlers often emit one string object, so
  * a bare `$(…)` interpolation would keep those newlines.
+ * Lists (`;` `&&` `||`) reuse translateListInline inside the fx-csub
+ * scriptblock so the newline contract is unchanged.
  */
-export declare function translateCmdSub(cmdText: string, keepNl?: boolean): string;
-export declare function translateSimple(cmd: SimpleCommand, position: PipelineCtx['position'], hasStdin: boolean): string;
+export declare function translateCmdSub(cmdText: string, keepNl?: boolean, translation?: TranslationContext): string;
+export declare function translateSimple(cmd: SimpleCommand, position: PipelineCtx['position'], hasStdin: boolean, translation?: TranslationContext): string;
 /** PS expr: encode a string so SETVALS records can stay newline-delimited. */
 export declare function encodeSetValExpr(srcExpr: string): string;
 /**
@@ -76,11 +109,11 @@ export interface PipelineParts {
     call: string;
 }
 export declare function translatePipelineBody(p: {
-    commands: Array<SimpleCommand | IfCommand | ForCommand>;
-}): PipelineParts;
+    commands: Array<SimpleCommand | IfCommand | ForCommand | WhileCommand | CaseCommand>;
+}, translation?: TranslationContext): PipelineParts;
 export interface SegmentPlan {
     op: ';' | '&&' | '||';
-    /** Spawn-mode wrapScript (CLI/MCP `translate`, one-shot powershell.exe). */
+    /** Spawn-mode wrapScript (`translate` output for a one-shot PowerShell process). */
     script: string;
     /** Pipeline body before wrapScript — executor host mode re-wraps this. */
     body: string;
@@ -91,7 +124,7 @@ export interface SegmentPlan {
     /** First-stage `<` only — FAUXNIX_STDIN_FILE feed. */
     stdinRedirects: Redirect[];
 }
-export declare function translateCommandList(list: CommandList): SegmentPlan[];
+export declare function translateCommandList(list: CommandList, translation?: TranslationContext): SegmentPlan[];
 export type WrapMode = 'spawn' | 'host';
 export interface WrapScriptOptions {
     /** spawn (default): one-shot process, `exit` at the end. host: no `exit`, no helper re-emit. */
@@ -106,6 +139,6 @@ export interface WrapScriptOptions {
 export declare function wrapScript(body: string, opts?: WrapScriptOptions): string;
 /**
  * Resident-host bootstrap: encoding + full fx-* catalog + JSON-line RPC loop.
- * Loaded once via `powershell.exe -File`. Must never `exit` a successful frame.
+ * Loaded once via the selected PowerShell's `-File`. Must never `exit` a successful frame.
  */
 export declare function hostBootstrapScript(): string;