@taliesinb/mash 0.0.0-stage → 0.1.0

package/dist/src/behaviors/defs/tools.js

@@ -0,0 +1,639 @@
+/**
+ * Behavior definitions for common command-line tools beyond coreutils:
+ * databases, document and media tools, downloaders, crypto, and local
+ * service CLIs. Most are table definitions (see ../dsl.ts); tools whose
+ * argument syntax the table cannot express (ffmpeg, sqlite3) are written out.
+ */
+import { concat, concrete, hole, known, knownPrefix } from "../../analysis/value.js";
+import { define } from "../dsl.js";
+const args = (inv) => inv.argv.slice(1);
+const isDash = (v) => concrete(v) === '-';
+const isUrl = (v) => /^[a-z][a-z0-9+.-]*:\/\//i.test(knownPrefix(v));
+/** Accepts any flags and operands; no effects of its own (query subcommands). */
+const QUERY = { anyFlags: true, operands: 'arg*', stdin: false };
+/** Changes state the definition cannot describe. */
+const opaque = (detail) => ({ anyFlags: true, operands: 'arg*', opaque: detail, stdin: 'maybe' });
+/** The directory part of a path value (`dir/` for `dir/x`), or undefined. */
+function dirOf(p) {
+    const s = concrete(p);
+    if (s === undefined)
+        return undefined;
+    const i = s.lastIndexOf('/');
+    return known(i <= 0 ? (i === 0 ? '/' : '.') : s.slice(0, i));
+}
+/** `x.typ` → `x.<ext>`: a sibling with another extension (unknown if the name is). */
+function sibling(p, ext) {
+    const s = concrete(p);
+    if (s !== undefined)
+        return known(s.replace(/\.[^./]*$/, '') + ext);
+    const d = dirOf(p);
+    return d ? concat(d, known('/'), hole('filename', 'output name')) : hole('path', 'output file');
+}
+// ---------------------------------------------------------------------------
+// sqlite3
+// ---------------------------------------------------------------------------
+/** Dot commands that only print or set display options. */
+const SQLITE_SAFE_DOT = /^\.(tables|schema|indexes|indices|headers?|mode|width|timer|timeout|nullvalue|separator|print|quit|exit|help|databases|changes|eqp|stats|bail|echo|show|dbinfo|fullschema|lint|selftrace|parameter|limits?|explain|columns|prompt|dump|version|vfsinfo|vfsname|vfslist|sha3sum|binary|crnl|expert|scanstats)\b/;
+function sqlTexts(v) {
+    const out = [];
+    for (const alt of v.alts) {
+        let s = '';
+        for (const seg of alt) {
+            if (typeof seg === 'string')
+                s += seg;
+            else if (seg.type === 'int')
+                s += '0';
+            // a string inside quotes can only be data if it has no quote of its own: not knowable
+            else
+                return undefined;
+        }
+        out.push(s);
+    }
+    return out;
+}
+const SQL_MODIFIES = /\b(insert|update|delete|replace|upsert|create|drop|alter|vacuum|reindex|analyze|begin|commit|savepoint|release|restore)\b|\bpragma\s+\w+(\.\w+)?\s*=|^\s*\.(restore|import)\b/im;
+const unquote = (w) => w.replace(/^(['"])(.*)\1$/, '$2');
+/**
+ * The files this SQL (with dot commands) touches beyond the database, or
+ * undefined when it can reach outside what can be described: other databases,
+ * extensions, the shell's file functions, `.read` scripts, pipes to commands.
+ */
+function sqlFiles(text) {
+    const files = [];
+    for (const line of text.split('\n')) {
+        const t = line.trim();
+        if (!t.startsWith('.') || SQLITE_SAFE_DOT.test(t))
+            continue;
+        const [cmd, ...words] = t.split(/\s+/).map(unquote);
+        const ops = words.filter((w) => !w.startsWith('-'));
+        const last = ops[ops.length - 1];
+        if (/^\.(backup|save|output|once)$/.test(cmd)) {
+            if (cmd === '.backup' || cmd === '.save' ? !last : false)
+                return undefined;
+            if (last === undefined)
+                continue; // `.output` alone: back to stdout
+            if (last.startsWith('|') || words.some((w) => /^-[ex]$/.test(w)))
+                return undefined; // to a command or an editor
+            files.push({ kind: 'write', file: last });
+        }
+        else if (cmd === '.import' && ops[0] && !ops[0].startsWith('|'))
+            files.push({ kind: 'read', file: ops[0] });
+        else
+            return undefined;
+    }
+    if (/\battach\b|\bvacuum\s+into\b|\b(load_extension|writefile|readfile|edit|fsdir|zipfile|sqlar_compress|sqlar_uncompress|lsmode)\s*\(/i.test(text.split('\n').filter((l) => !l.trim().startsWith('.')).join('\n')))
+        return undefined;
+    return files;
+}
+const sqlite3 = {
+    names: ['sqlite3', 'sqlite'],
+    summary: 'SQLite shell (sqlite3 [opts] DB [SQL...])',
+    analyze(inv, h) {
+        const p = h.parseArgs(args(inv), {
+            longSingle: true,
+            long: {
+                readonly: false, header: false, noheader: false, column: false, csv: false, json: false, line: false, list: false, box: false, markdown: false, table: false, html: false, tabs: false, quote: false, ascii: false,
+                batch: false, bail: false, echo: false, interactive: false, safe: false, nofollow: false, stats: false, version: false, help: false, memtrace: false, unsafe_testing: false,
+                separator: true, newline: true, nullvalue: true, cmd: true, init: true, vfs: true, mmap: true, append: false, deserialize: false, maxsize: true, nonce: true, A: true, zip: false,
+            },
+        });
+        if (p.flags.has('version') || p.flags.has('help'))
+            return { effects: [], readsStdin: false };
+        const [db, ...sql] = p.operands;
+        const effects = [];
+        let complete = p.unknownFlags.length === 0 && !p.flags.has('A') && !p.flags.has('zip');
+        const init = p.flags.get('init');
+        if (init && init !== true) {
+            effects.push({ kind: 'read', path: h.resolve(init) });
+            complete = false;
+        }
+        const programs = [...sql, ...(p.multi.get('cmd') ?? [])];
+        for (const s of programs) {
+            h.role(s, 'code');
+            for (const text of sqlTexts(s) ?? [undefined]) {
+                const files = text === undefined ? undefined : sqlFiles(text);
+                if (!files)
+                    complete = false;
+                for (const f of files ?? [])
+                    effects.push({ kind: f.kind, path: h.resolve(known(f.file)) });
+            }
+        }
+        const name = db === undefined ? '' : concrete(db);
+        if (db !== undefined && name !== '' && name !== ':memory:') {
+            if (knownPrefix(db).startsWith('file:'))
+                complete = false;
+            const path = h.resolve(db);
+            effects.push({ kind: 'read', path });
+            if (!p.flags.has('readonly')) {
+                // statements that change the database write it; unknown or stdin SQL may
+                const texts = programs.map((v) => sqlTexts(v));
+                const modifies = texts.some((t) => t?.some((x) => SQL_MODIFIES.test(x)));
+                const unknown = texts.some((t) => t === undefined) || sql.length === 0;
+                if (modifies || unknown)
+                    effects.push({ kind: 'write', path, ...(modifies ? {} : { maybe: true }) });
+                // even reads may create the -wal/-shm/-journal siblings
+                effects.push({ kind: 'write', path: { alts: ['-wal', '-shm', '-journal'].flatMap((sfx) => path.alts.map((a) => [...a, sfx])) }, maybe: true });
+            }
+        }
+        // no SQL arguments: statements come from stdin
+        if (sql.length === 0) {
+            if (programs.length === 0)
+                complete = false;
+            return { effects, readsStdin: true, complete };
+        }
+        return { effects, readsStdin: false, complete };
+    },
+};
+// ---------------------------------------------------------------------------
+// typst
+// ---------------------------------------------------------------------------
+const TYPST_GLOBAL = { short: 'hV', long: { help: false, version: false, color: true, cert: true } };
+const TYPST_WORLD = {
+    root: true, input: true, 'font-path': true, 'ignore-system-fonts': false, 'ignore-embedded-fonts': false, 'package-path': true, 'package-cache-path': true,
+    'creation-timestamp': true, features: true, 'diagnostic-format': true, jobs: '=j', format: '=f', ppi: true, pages: true, 'pdf-standard': true, 'no-pdf-tags': false,
+    'make-deps': true, deps: true, 'deps-format': true, open: true, timings: true, field: true, one: false, target: true, pretty: false, 'no-serve': false, 'no-reload': false, port: true,
+};
+/** typst compile/watch/query: reads the project (input's directory or --root), may fetch packages. */
+function typstCompile(withOutput) {
+    return {
+        spec: { shortWithArg: 'jf', long: TYPST_WORLD },
+        operands: withOutput ? 'read write?' : 'read pattern?',
+        flags: { 'font-path': 'read:dir', 'make-deps': 'write', deps: 'write', timings: 'write' },
+        extra: (r, { inv, h, p, operands }) => {
+            const effects = [...r.effects];
+            const [input, output] = operands;
+            const rootFlag = p.flags.get('root');
+            const root = rootFlag && rootFlag !== true ? h.resolve(rootFlag) : input && !isDash(input) ? dirOf(h.resolve(input)) : inv.cwd;
+            if (root)
+                effects.push({ kind: 'read', path: root, recursive: true });
+            if (withOutput && input && !output && !isDash(input)) {
+                const fmt = concrete(p.flags.get('f') ?? known('pdf')) ?? 'pdf';
+                effects.push({ kind: 'write', path: sibling(h.resolve(input), '.' + fmt) });
+            }
+            // `@preview` packages are downloaded into the cache on first use
+            effects.push({ kind: 'network', detail: 'typst packages', maybe: true });
+            const cache = p.flags.get('package-cache-path');
+            effects.push(cache && cache !== true
+                ? { kind: 'write', path: h.resolve(cache), recursive: true, maybe: true }
+                : { kind: 'write', path: concat(h.home() ?? known('~'), known(process.platform === 'darwin' ? '/Library/Caches/typst' : '/.cache/typst')), recursive: true, maybe: true });
+            const complete = r.complete !== false && !p.flags.has('open');
+            return { ...r, effects, complete, readsStdin: input !== undefined && isDash(input) };
+        },
+    };
+}
+const typst = define({
+    names: ['typst'], summary: 'typesetting', spec: TYPST_GLOBAL,
+    subcommands: {
+        'compile|c': typstCompile(true),
+        'watch|w': typstCompile(true),
+        'query|q': { ...typstCompile(false), stdout: { type: 'string' } },
+        fonts: { spec: { long: { 'font-path': true, 'ignore-system-fonts': false, 'ignore-embedded-fonts': false, variants: false } }, flags: { 'font-path': 'read:dir' }, stdin: false },
+        'init|update': opaque('typst downloads templates or updates itself'),
+        help: QUERY,
+    },
+});
+// ---------------------------------------------------------------------------
+// ffmpeg / ffprobe
+// ---------------------------------------------------------------------------
+const FFMPEG_BOOL = new Set([
+    '-y', '-n', '-nostdin', '-stdin', '-hide_banner', '-stats', '-nostats', '-an', '-vn', '-sn', '-dn', '-shortest', '-re', '-benchmark', '-benchmark_all', '-copyts', '-start_at_zero',
+    '-accurate_seek', '-noaccurate_seek', '-autorotate', '-noautorotate', '-ignore_unknown', '-copy_unknown', '-dump', '-hex', '-xerror', '-bitexact', '-debug_ts', '-version', '-h', '-help',
+    '-formats', '-codecs', '-encoders', '-decoders', '-filters', '-pix_fmts', '-layouts', '-sample_fmts', '-protocols', '-muxers', '-demuxers', '-devices', '-bsfs', '-buildconf', '-hwaccels',
+    '-show_format', '-show_streams', '-show_packets', '-show_frames', '-show_chapters', '-show_programs', '-show_error', '-show_data', '-show_private_data', '-show_program_version',
+    '-show_library_versions', '-show_versions', '-show_pixel_formats', '-count_frames', '-count_packets', '-pretty', '-unit', '-prefix', '-byte_binary_prefix', '-sexagesimal', '-show_optional_fields',
+    '-shortest_buf_duration', '-dts_delta_threshold', '-vsync', '-fix_sub_duration', '-apad', '-nostdin',
+]);
+/** Options whose value names a file read or written. */
+const FFMPEG_READS = new Set(['-filter_complex_script', '-filter_script', '-attach', '-i']);
+const FFMPEG_WRITES = new Set(['-vstats_file', '-passlogfile', '-progress', '-o']);
+const FFMPEG_PATH_VALUE = new Set([...FFMPEG_READS, ...FFMPEG_WRITES, '-dump_attachment']);
+const ffmpeg = {
+    names: ['ffmpeg', 'ffprobe', 'ffplay'],
+    summary: 'audio/video conversion',
+    analyze(inv, h) {
+        const a = args(inv);
+        const probe = inv.name !== 'ffmpeg';
+        const effects = [];
+        const inputs = [];
+        const outputs = [];
+        let complete = true;
+        let nostdin = probe;
+        let stdinInput = false;
+        for (let i = 0; i < a.length; i++) {
+            const s = concrete(a[i]);
+            if (s === undefined) {
+                // an unknown word that may be an option (and then perhaps take a value): not known
+                if (knownPrefix(a[i]).startsWith('-'))
+                    complete = false;
+                else
+                    (probe ? inputs : outputs).push(a[i]);
+                continue;
+            }
+            if (s === '-' || !s.startsWith('-')) {
+                ;
+                (probe ? inputs : outputs).push(a[i]);
+                continue;
+            }
+            if (s === '-nostdin')
+                nostdin = true;
+            if (FFMPEG_BOOL.has(s) || (/^-(no)?(show|count)_/.test(s) && s !== '-show_entries' && s !== '-show_optional_fields'))
+                continue;
+            if (s === '-report') {
+                effects.push({ kind: 'write', path: concat(inv.cwd, known('/'), hole('filename', 'ffmpeg report')) });
+                continue;
+            }
+            const v = a[++i];
+            if (v === undefined)
+                break;
+            const name = s.replace(/:.*$/, '');
+            // a path-like value for an option not known to take one: maybe a boolean option we do not know, then an output file
+            if (!FFMPEG_PATH_VALUE.has(name) && /\/|\.[A-Za-z0-9]{2,4}$/.test(concrete(v) ?? '') && !/^-(metadata|vf|af|filter|filter_complex|lavfi|map|ss|t|to|sseof|f|c|codec|tag)$/.test(name))
+                complete = false;
+            if (name === '-i')
+                inputs.push(v);
+            else if (FFMPEG_READS.has(name))
+                effects.push({ kind: 'read', path: h.resolve(v) });
+            else if (FFMPEG_WRITES.has(name)) {
+                if (!isDash(v) && !isUrl(v) && concrete(v) !== 'pipe:1')
+                    effects.push({ kind: 'write', path: h.resolve(v) });
+            }
+            else if (/^-(vf|af|filter|filter_complex|lavfi)$/.test(name)) {
+                h.role(v, 'code');
+                // filters can open (movie=, subtitles=) or write (file=, stats_file=) files
+                const t = concrete(v);
+                if (t === undefined || /\b(movie|amovie|subtitles|ass|lut3d|lut1d|haldclut|sendcmd|asendcmd|zmq|azmq|file|filename|stats_file|result|f|ocr)\s*=/.test(t) || /\bf=/.test(t))
+                    complete = false;
+            }
+            else if (name === '-f' && /^(concat|lavfi|tee|segment|hls|dash|image2pipe|fifo)$/.test(concrete(v) ?? '')) {
+                // inputs listing other files, filter-graph inputs, several outputs
+                if (!/^(segment|hls|dash)$/.test(concrete(v)))
+                    complete = false;
+            }
+        }
+        for (const v of inputs) {
+            const t = concrete(v);
+            if (t === '-' || t === 'pipe:' || t === 'pipe:0')
+                stdinInput = true;
+            else if (isUrl(v))
+                effects.push({ kind: 'network', target: v, detail: inv.name });
+            else if (t !== undefined && /^[a-z]+:/.test(t) && !/^file:/.test(t))
+                complete = false; // concat:, subfile:, … protocols
+            else
+                effects.push({ kind: 'read', path: h.resolve(v) });
+        }
+        for (const v of outputs) {
+            const t = concrete(v);
+            if (t === '-' || t === 'pipe:' || t === 'pipe:1')
+                continue;
+            if (isUrl(v))
+                effects.push({ kind: 'network', target: v, detail: inv.name });
+            else
+                effects.push({ kind: 'write', path: h.resolve(v) });
+        }
+        // ffmpeg reads keyboard commands from stdin unless -nostdin
+        return { effects, readsStdin: stdinInput || (nostdin ? false : 'maybe'), complete };
+    },
+};
+// ---------------------------------------------------------------------------
+// yt-dlp
+// ---------------------------------------------------------------------------
+const ytdlp = define({
+    names: ['yt-dlp', 'youtube-dl'], summary: 'download videos',
+    spec: {
+        short: 'FqvsjJgeixwciUN', shortWithArg: 'foPNraRIS',
+        long: {
+            format: '=f', 'list-formats': '=F', output: '=o', paths: '=P', 'concurrent-fragments': '=N', quiet: '=q', verbose: '=v', 'no-progress': false, progress: false, 'no-part': false,
+            'cookies-from-browser': true, cookies: true, 'extractor-args': true, 'skip-download': false, print: true, 'print-to-file': 2, 'flat-playlist': false, 'dump-json': '=j', 'dump-single-json': '=J',
+            simulate: '=s', 'no-simulate': false, version: false, help: false, 'get-url': '=g', 'get-title': '=e', 'extract-audio': '=x', 'audio-format': true, 'audio-quality': true, 'merge-output-format': true,
+            'remux-video': true, 'recode-video': true, 'write-subs': false, 'write-auto-subs': false, 'sub-langs': true, 'sub-format': true, 'embed-subs': false, 'write-thumbnail': false, 'embed-thumbnail': false,
+            'embed-metadata': false, 'no-playlist': false, 'yes-playlist': false, 'playlist-items': '=I', 'limit-rate': '=r', retries: '=R', 'batch-file': '=a', 'no-warnings': false, 'no-overwrites': '=w',
+            continue: '=c', newline: false, 'restrict-filenames': false, impersonate: true, 'user-agent': true, referer: true, 'add-header': true, 'socket-timeout': true, 'sleep-interval': true,
+            'ignore-errors': '=i', 'abort-on-error': false, 'download-sections': true, 'force-overwrites': false, 'no-mtime': false, 'write-info-json': false, 'write-description': false, 'list-subs': false,
+            'list-thumbnails': false, 'get-filename': false, 'no-cache-dir': false, 'cache-dir': true, proxy: true, 'geo-bypass': false, 'match-filters': true, 'match-filter': true, 'download-archive': true,
+            'js-runtimes': true, 'remote-components': true, 'format-sort': '=S', 'no-color': false, 'max-downloads': true, 'min-filesize': true, 'max-filesize': true, 'date': true, 'dateafter': true, 'datebefore': true,
+            'exec': true, 'update': '=U', 'external-downloader': true, 'downloader': true, 'postprocessor-args': true, 'ppa': true, 'ffmpeg-location': true, 'split-chapters': false, 'trim-filenames': true, 'windows-filenames': false,
+        },
+    },
+    operands: 'url*', stdin: false,
+    flags: { a: 'read', cookies: 'read', 'download-archive': 'append', 'print-to-file': 'append', P: 'write:dir' },
+    extra: (r, { inv, h, p }) => {
+        const effects = [...r.effects];
+        const noDownload = ['F', 'j', 'J', 's', 'g', 'e', 'skip-download', 'list-subs', 'list-thumbnails', 'get-filename', 'version', 'help', 'print'].some((k) => p.flags.has(k)) && !p.flags.has('no-simulate');
+        if (p.flags.has('version') || p.flags.has('help'))
+            return { effects: [], readsStdin: false };
+        if (!noDownload) {
+            const o = p.flags.get('o');
+            const P = p.flags.get('P');
+            const base = P && P !== true ? h.resolve(P) : inv.cwd;
+            // the output template (and the merged/temporary files next to it); a template may add directories
+            const out = o && o !== true && !isDash(o) ? (knownPrefix(o).startsWith('/') ? o : concat(base, known('/'), o)) : concat(base, known('/'), hole('filename', 'video title'));
+            if (!(o && o !== true && isDash(o)))
+                effects.push({ kind: 'write', path: out });
+        }
+        const cookies = p.flags.get('cookies');
+        if (cookies && cookies !== true)
+            effects.push({ kind: 'write', path: h.resolve(cookies), maybe: true });
+        // the browser's profile (cookie store)
+        if (p.flags.has('cookies-from-browser'))
+            effects.push({ kind: 'read', path: concat(h.home() ?? known('~'), known(process.platform === 'darwin' ? '/Library' : '/.config')), recursive: true, maybe: true });
+        if (!p.flags.has('no-cache-dir'))
+            effects.push({ kind: 'write', path: concat(h.home() ?? known('~'), known('/.cache/yt-dlp')), recursive: true, maybe: true });
+        // --exec runs commands; --update replaces the program; external downloaders run other programs
+        const complete = r.complete !== false && !['exec', 'U', 'external-downloader', 'downloader', 'postprocessor-args', 'ppa'].some((k) => p.flags.has(k));
+        // URLs from a batch file (or none given): still network
+        if (!effects.some((e) => e.kind === 'network'))
+            effects.unshift({ kind: 'network', detail: inv.name });
+        return { ...r, effects, complete, readsStdin: p.flags.has('a') && isDash(p.flags.get('a')) };
+    },
+});
+// ---------------------------------------------------------------------------
+// PDF tools (poppler), ImageMagick identify
+// ---------------------------------------------------------------------------
+const POPPLER_SHORT = { short: 'qvh', shortWithArg: 'flrxyWH' };
+const POPPLER_LONG = { opw: true, upw: true, q: false, v: false, h: false, help: false, enc: true, f: true, l: true, r: true, x: true, y: true, W: true, H: true, cropbox: false, nodiag: false };
+const pdftools = [
+    define({
+        names: ['pdftotext'], summary: 'PDF to text (pdftotext in.pdf [out.txt|-])',
+        spec: { ...POPPLER_SHORT, longSingle: true, long: { ...POPPLER_LONG, layout: false, fixed: true, raw: false, htmlmeta: false, bbox: false, 'bbox-layout': false, tsv: false, eol: true, nopgbrk: false, colspacing: true } },
+        operands: 'read write?', stdin: false,
+        extra: (r, { h, operands }) => {
+            const [input, output] = operands;
+            if (output && isDash(output))
+                return { ...r, effects: r.effects.filter((e) => e.kind !== 'write') };
+            if (input && !output && !isDash(input))
+                return { ...r, effects: [...r.effects, { kind: 'write', path: sibling(h.resolve(input), '.txt') }] };
+            return r;
+        },
+    }),
+    define({
+        names: ['pdfinfo', 'pdffonts', 'pdfsig', 'pdfdetach'], summary: 'inspect PDFs',
+        spec: { ...POPPLER_SHORT, longSingle: true, long: { ...POPPLER_LONG, box: false, meta: false, js: false, struct: false, 'struct-text': false, rawdates: false, isodates: false, dests: false, url: false, listenc: false, subst: false, list: false, nodump: false } },
+        operands: 'read*', stdin: false,
+        when: { saveall: { opaque: 'pdfdetach writes attachments' }, save: { opaque: 'pdfdetach writes attachments' } },
+    }),
+    define({
+        names: ['pdftoppm', 'pdftocairo', 'pdfimages'], summary: 'render PDF pages to images (… in.pdf ROOT)',
+        spec: { ...POPPLER_SHORT, longSingle: true, long: { ...POPPLER_LONG, png: false, jpeg: false, tiff: false, ppm: false, pdf: false, ps: false, eps: false, svg: false, j: false, all: false, list: false, p: false, print: false, 'scale-to': true, 'scale-to-x': true, 'scale-to-y': true, singlefile: false, gray: false, mono: false, jpegopt: true, aa: true, aaVector: true, rx: true, ry: true, sep: true, forcenum: false, 'transp': false, 'hide-annotations': false, 'o': false, 'e': false, 'struct': false } },
+        operands: 'read arg?', stdin: false,
+        // pages are written as ROOT-N.ext (or ROOT.ext): a name starting with ROOT
+        extra: (r, { h, operands }) => {
+            const root = operands[1];
+            if (!root || isDash(root))
+                return r;
+            const base = h.resolve(root);
+            return { ...r, effects: [...r.effects, { kind: 'write', path: { alts: base.alts.map((a) => [...a, hole('filename', 'page suffix').alts[0][0]]) } }] };
+        },
+    }),
+    define({ names: ['pdfunite'], summary: 'merge PDFs (pdfunite in... out)', spec: { short: 'vh', longSingle: true, long: { help: false } }, operands: 'read* write', stdin: false }),
+    define({ names: ['pdfseparate'], summary: 'split a PDF (pdfseparate in out-%d.pdf)', spec: { short: 'vh', shortWithArg: 'fl', longSingle: true }, operands: 'read write', stdin: false }),
+    define({
+        names: ['identify'], summary: 'describe images (ImageMagick)',
+        spec: { longSingle: true, long: { format: true, verbose: false, ping: false, quiet: false, 'regard-warnings': false, density: true, units: true, precision: true, define: true, moments: false, features: true, unique: false, size: true, depth: true, list: true, version: false, help: false, colorspace: true, channel: true, alpha: true, auto_orient: false, debug: true, limit: 2, monitor: false } },
+        operands: 'read*', stdin: false,
+        // `@list` reads file names from a file; coders like `msl:` run scripts
+        extra: (r, { operands }) => (operands.some((o) => /^@|^[a-z]{2,}:/i.test(knownPrefix(o)) || concrete(o) === undefined && knownPrefix(o) === '') ? { ...r, complete: false } : r),
+    }),
+];
+// ---------------------------------------------------------------------------
+// crypto and keys
+// ---------------------------------------------------------------------------
+/** openssl SUBCOMMAND with single-dash options: -in/-key/… read, -out/-keyout write. */
+const OPENSSL_READ = new Set(['-in', '-key', '-inkey', '-CAfile', '-CA', '-CAkey', '-cert', '-certfile', '-config', '-signature', '-extfile', '-paramfile', '-kfile', '-verify', '-prverify', '-peerkey', '-sigfile', '-untrusted', '-chain', '-CRLfile', '-passin', '-dcert', '-dkey', '-reqin', '-signkey', '-CAserial', '-rand']);
+const OPENSSL_WRITE = new Set(['-out', '-keyout', '-sessout', '-msgfile', '-signer', '-pubout_file']);
+const OPENSSL_READONLY = new Set(['version', 'rand', 'x509', 'dgst', 'md5', 'sha1', 'sha256', 'sha384', 'sha512', 'base64', 'enc', 'req', 'rsa', 'ec', 'pkey', 'pkeyutl', 'verify', 'asn1parse', 'crl', 'pkcs7', 'pkcs12', 'cms', 'smime', 'genrsa', 'genpkey', 'ecparam', 'dhparam', 'prime', 'passwd', 'list', 'help', 'speed', 'errstr', 'ciphers', 'kdf', 'mac', 'storeutl', 'nseq', 'spkac', 'ts', 'rsautl', 'gendsa', 'dsa', 'dsaparam', 'crl2pkcs7', 'sess_id', 'info']);
+const openssl = {
+    names: ['openssl'],
+    summary: 'cryptography toolkit',
+    analyze(inv, h) {
+        const a = args(inv);
+        const sub = concrete(a[0] ?? known('')) ?? '';
+        if (a[0])
+            h.role(a[0], 'subcommand');
+        const effects = [];
+        if (sub === 's_client' || sub === 's_time' || sub === 'ocsp') {
+            return { effects: [{ kind: 'network', detail: `openssl ${sub}`, target: a.slice(1).find((_, k) => concrete(a[k]) === '-connect') }], readsStdin: true, complete: true };
+        }
+        if (!OPENSSL_READONLY.has(sub))
+            return { effects: [{ kind: 'unknown', detail: `openssl ${sub || '(interactive)'}` }], readsStdin: 'maybe', complete: false };
+        let complete = true;
+        let readsIn = false;
+        let explicitIn = false;
+        const operands = [];
+        for (let i = 1; i < a.length; i++) {
+            const s = concrete(a[i]);
+            if (s === undefined) {
+                complete = false;
+                continue;
+            }
+            if (!s.startsWith('-') || s === '-') {
+                operands.push(a[i]);
+                continue;
+            }
+            const v = a[i + 1];
+            if (OPENSSL_READ.has(s) && v) {
+                i++;
+                if (s === '-in')
+                    explicitIn = true;
+                const t = concrete(v);
+                if (s === '-passin') {
+                    if (t?.startsWith('file:'))
+                        effects.push({ kind: 'read', path: h.resolve(known(t.slice(5))) });
+                    continue;
+                }
+                if (t === '-' || t === 'stdin')
+                    readsIn = true;
+                else
+                    effects.push({ kind: 'read', path: h.resolve(v) });
+            }
+            else if (OPENSSL_WRITE.has(s) && v) {
+                i++;
+                if (!isDash(v))
+                    effects.push({ kind: 'write', path: h.resolve(v) });
+            }
+            else if (s === '-engine' || s === '-provider-path' || s === '-provider') {
+                // loads code
+                complete = false;
+                i++;
+            }
+            else if (s === '-sign' || s === '-hmac' || s === '-mac' || s === '-pass' || s === '-passout' || s === '-subj' || s === '-days' || s === '-newkey' || s === '-name' || s === '-digest' || s === '-cipher' || s === '-pkeyopt' || s === '-sigopt' || s === '-nameopt' || s === '-certopt' || s === '-set_serial' || s === '-addext' || s === '-extensions' || s === '-section' || s === '-K' || s === '-iv' || s === '-S' || s === '-md' || s === '-iter' || s === '-inform' || s === '-outform' || s === '-keyform' || s === '-certform' || s === '-algorithm' || s === '-macopt' || s === '-kdfopt' || s === '-keylen' || s === '-bits' || s === '-group' || s === '-servername' || s === '-connect') {
+                if (s === '-sign' && v)
+                    effects.push({ kind: 'read', path: h.resolve(v) });
+                if (s === '-passout' && concrete(v ?? known(''))?.startsWith('file:'))
+                    effects.push({ kind: 'write', path: h.resolve(known(concrete(v).slice(5))) });
+                i++;
+            }
+        }
+        // dgst/sha*/x509 … take files as operands; rand/prime take numbers
+        const fileOps = ['dgst', 'md5', 'sha1', 'sha256', 'sha384', 'sha512', 'asn1parse'].includes(sub);
+        if (fileOps)
+            for (const o of operands)
+                if (!isDash(o))
+                    effects.push({ kind: 'read', path: h.resolve(o) });
+        const usesStdin = !explicitIn && !['version', 'rand', 'help', 'list', 'genrsa', 'genpkey', 'ecparam', 'prime', 'speed', 'errstr', 'ciphers', 'kdf', 'passwd', 'dhparam', 'gendsa', 'dsaparam'].includes(sub) && !(fileOps && operands.length > 0);
+        return { effects, readsStdin: readsIn || usesStdin, complete };
+    },
+};
+const sshKeygen = {
+    names: ['ssh-keygen'],
+    summary: 'create and inspect SSH keys',
+    analyze(inv, h) {
+        const p = h.parseArgs(args(inv), { short: 'ABcDeEHiklLmMpqQrRuUvyYgK', shortWithArg: 'abCEfFgIJjmNnOPrRstVwYzZDTGSM' });
+        const effects = [];
+        const home = h.home() ?? known('~');
+        const f = p.flags.get('f');
+        const file = f && f !== true ? h.resolve(f) : undefined;
+        const knownHosts = file ?? concat(home, known('/.ssh/known_hosts'));
+        const query = ['l', 'y', 'B', 'e', 'i', 'D', 'k', 'Q', 'L'].some((k) => p.flags.has(k));
+        let complete = p.unknownFlags.length === 0;
+        if (p.flags.has('R') || p.flags.has('H'))
+            effects.push({ kind: 'write', path: knownHosts });
+        else if (p.flags.has('F'))
+            effects.push({ kind: 'read', path: knownHosts });
+        else if (p.flags.has('Y')) {
+            const mode = concrete(p.flags.get('Y')) ?? '';
+            if (file)
+                effects.push({ kind: 'read', path: file });
+            for (const o of p.operands) {
+                effects.push({ kind: 'read', path: h.resolve(o) });
+                if (mode === 'sign')
+                    effects.push({ kind: 'write', path: concat(h.resolve(o), known('.sig')) });
+            }
+            if (mode !== 'sign' && mode !== 'verify' && mode !== 'check-novalidate' && mode !== 'find-principals')
+                complete = false;
+        }
+        else if (query || p.flags.has('p') || p.flags.has('c')) {
+            if (file)
+                effects.push({ kind: (p.flags.has('p') || p.flags.has('c')) ? 'write' : 'read', path: file });
+            else
+                complete = false; // prompts for the file
+        }
+        else {
+            // key generation: FILE and FILE.pub (default ~/.ssh/id_TYPE, asked interactively)
+            if (file)
+                effects.push({ kind: 'write', path: file }, { kind: 'write', path: concat(file, known('.pub')) });
+            else {
+                effects.push({ kind: 'write', path: concat(home, known('/.ssh/'), hole('filename', 'key name')) });
+                complete = false;
+            }
+        }
+        return { effects, readsStdin: !p.flags.has('N') || !file ? 'maybe' : false, complete };
+    },
+};
+// ---------------------------------------------------------------------------
+// developer tools that do not run project code
+// ---------------------------------------------------------------------------
+/** tsc: reads the project; emits only without --noEmit (outDir comes from tsconfig: not known). */
+const TSC_VALUE = new Set(['-p', '--project', '--module', '-m', '--moduleResolution', '--target', '-t', '--lib', '--jsx', '--types', '--typeRoots', '--outDir', '--rootDir', '--rootDirs', '--baseUrl', '--declarationDir', '--outFile', '--tsBuildInfoFile', '--generateTrace', '--locale', '--maxNodeModuleJsDepth', '--ignoreDeprecations', '--moduleDetection', '--newLine', '--paths', '--customConditions', '--watchFile', '--watchDirectory', '--fallbackPolling', '--excludeDirectories', '--excludeFiles', '--jsxFactory', '--jsxFragmentFactory', '--jsxImportSource', '--importsNotUsedAsValues', '--moduleSuffixes', '--plugins', '--extendedDiagnostics', '--generateCpuProfile', '--explainFiles', '--listEmittedFiles', '--diagnostics']);
+const tsc = {
+    names: ['tsc'],
+    summary: 'TypeScript compiler',
+    analyze(inv, h) {
+        const a = args(inv);
+        const s = a.map((x) => concrete(x));
+        if (s.length === 1 && ['-v', '--version', '-h', '--help', '--all'].includes(s[0] ?? ''))
+            return { effects: [], readsStdin: false };
+        let dir = inv.cwd;
+        const effects = [];
+        const files = [];
+        let noEmit = false;
+        let complete = true;
+        for (let i = 0; i < a.length; i++) {
+            const t = s[i];
+            if (t === undefined) {
+                complete = false;
+                continue;
+            }
+            if (t === '--noEmit' && s[i + 1] !== 'false')
+                noEmit = true;
+            if (TSC_VALUE.has(t) && a[i + 1]) {
+                const v = a[++i];
+                if (t === '-p' || t === '--project')
+                    dir = h.resolve(v);
+                else if (t === '--generateTrace' || t === '--tsBuildInfoFile' || t === '--generateCpuProfile')
+                    effects.push({ kind: 'write', path: h.resolve(v), recursive: t === '--generateTrace' });
+                else if (t === '--outDir' || t === '--declarationDir' || t === '--outFile')
+                    effects.push({ kind: 'write', path: h.resolve(v), recursive: t !== '--outFile', maybe: true });
+                continue;
+            }
+            if (t.startsWith('-')) {
+                if (s[i + 1] === 'true' || s[i + 1] === 'false')
+                    i++;
+                continue;
+            }
+            files.push(a[i]);
+        }
+        for (const f of files)
+            effects.push({ kind: 'read', path: h.resolve(f) });
+        effects.unshift({ kind: 'read', path: dir, recursive: true });
+        if (!noEmit) {
+            // emits next to the sources or into tsconfig's outDir
+            effects.push({ kind: 'write', path: dir, recursive: true, maybe: true });
+            complete = false;
+        }
+        return { effects, readsStdin: false, complete };
+    },
+};
+/** Linters and formatters: read their operands (or the cwd); fix/write flags rewrite them. */
+const LINT = {
+    anyFlags: true, operands: 'read*', cwdIfNone: true, recursive: true, stdin: false,
+    spec: { long: { fix: false, write: false, unsafe: false, 'unsafe-fixes': false, 'fix-only': false, 'fix-dangerously': false, apply: false, 'apply-unsafe': false, diff: false, check: false, config: true, 'config-path': true, format: true, 'output-format': true, select: true, ignore: true, 'extend-select': true, 'target-version': true, 'line-length': true, 'max-diagnostics': true, reporter: true, severity: true, shell: true, exclude: true, include: true } },
+    flags: { config: 'read', 'config-path': 'read' },
+    when: { 'fix|write|unsafe|unsafe-fixes|fix-only|fix-dangerously|apply|apply-unsafe': { operands: 'write*' } },
+};
+const lintTools = [
+    define({ names: ['oxlint', 'shellcheck', 'markdownlint', 'markdownlint-cli2', 'actionlint', 'hadolint', 'yamllint', 'eslint_d'], summary: 'linters (read files; --fix rewrites them)', ...LINT }),
+    define({
+        names: ['ruff', 'biome', 'taplo'], summary: 'linters / formatters', spec: { long: { version: false, help: false } },
+        subcommands: {
+            'check|lint|ci': LINT,
+            // `ruff format` and `taplo fmt` rewrite files unless --check/--diff; `biome format` only with --write
+            'format|fmt': { ...LINT, extra: (r, { inv, p }) => (inv.name !== 'biome' && !p.flags.has('check') && !p.flags.has('diff') ? { ...r, effects: r.effects.map((e) => (e.kind === 'read' ? { kind: 'write', path: e.path, recursive: true } : e)) } : r) },
+            'version|help|rule|explain|rage|config|linter|analyze': QUERY,
+            '*': opaque('linter subcommand'),
+        },
+    }),
+];
+// ---------------------------------------------------------------------------
+// local daemons and services
+// ---------------------------------------------------------------------------
+const lms = define({
+    names: ['lms'], summary: 'LM Studio CLI', spec: { short: 'h', long: { help: false, version: false } },
+    subcommands: {
+        'ps|ls|status|version|help|log': QUERY,
+        'load|unload|server': { ...QUERY, effects: [{ kind: 'process', detail: 'LM Studio server state' }] },
+        get: { ...QUERY, effects: [{ kind: 'network', detail: 'lms get' }, { kind: 'write', path: '~/.lmstudio', recursive: true, maybe: true }] },
+        '*': opaque('lms'),
+    },
+});
+const tailscale = define({
+    names: ['tailscale'], summary: 'Tailscale CLI', spec: { long: { socket: true, help: false, version: false } },
+    subcommands: {
+        'status|ip|version|whoami|dns|exit-node|metrics|licenses|bugreport|help|completion': QUERY,
+        'ping|netcheck|nc': { ...QUERY, effects: [{ kind: 'network', detail: 'tailscale' }] },
+        'switch': { ...QUERY, when: { list: QUERY }, opaque: 'tailscale switch changes the account' },
+        'serve|funnel': { ...opaque('tailscale serve changes the node configuration'), when: { json: QUERY } },
+        '*': opaque('tailscale changes the node configuration'),
+    },
+});
+const netlify = define({
+    names: ['netlify', 'ntl'], summary: 'Netlify CLI', spec: { long: { version: false, help: false, debug: false, auth: true } },
+    subcommands: {
+        'status|sites:list|sites:create|api|env:list|env:get|open:admin|watch|logs|logs:function|functions:list|teams:list|help|status:hooks|unlink|switch': { ...QUERY, effects: [{ kind: 'network', detail: 'netlify' }] },
+        // builds run project code unless --no-build
+        deploy: { anyFlags: true, operands: 'arg*', stdin: false, spec: { long: { dir: true, functions: true, 'no-build': false, prod: false, site: true, message: true, alias: true, json: false } }, flags: { dir: 'read:dir', functions: 'read:dir' }, effects: [{ kind: 'network', detail: 'netlify deploy' }, { kind: 'write', path: '.netlify', recursive: true, maybe: true }], recursive: true, opaque: 'netlify deploy may run the build', when: { 'no-build': { opaque: undefined } } },
+        '*': opaque('netlify runs project scripts or changes the site'),
+    },
+});
+const hf = define({
+    names: ['hf', 'huggingface-cli'], summary: 'Hugging Face CLI', spec: { long: { help: false, version: false, token: true } },
+    subcommands: {
+        'whoami|env|version|help': { ...QUERY, effects: [{ kind: 'network', detail: 'hf', maybe: true }] },
+        download: { ...QUERY, spec: { long: { 'local-dir': true, 'cache-dir': true } }, flags: { 'local-dir': 'write:dir', 'cache-dir': 'write:dir' }, effects: [{ kind: 'network', detail: 'hf download' }, { kind: 'write', path: '~/.cache/huggingface', recursive: true, maybe: true }] },
+        upload: { anyFlags: true, operands: 'arg read*', stdin: false, recursive: true, effects: [{ kind: 'network', detail: 'hf upload' }] },
+        '*': opaque('hf'),
+    },
+});
+export const toolBehaviors = [
+    sqlite3, typst, ffmpeg, ytdlp, ...pdftools, openssl, sshKeygen, tsc, ...lintTools, lms, tailscale, netlify, hf,
+];
+//# sourceMappingURL=tools.js.map