fullcourtdefense-cli 1.35.2 → 1.35.3

package/dist/commandNarrative.js

@@ -0,0 +1,602 @@
+"use strict";
+/**
+ * What a shell script DOES, one plain-words line per step — for the approval
+ * dialog and the IDE message. A developer asked to approve
+ *
+ *   $prefix="gs://b/prod-export"; gcloud firestore export $prefix --project acme-prod; gcloud firestore import $prefix --project acme-staging
+ *
+ * should read "Exports Firestore data from project acme-prod to bucket b ·
+ * Imports Firestore data into project acme-staging from bucket b", not a
+ * truncated command line.
+ *
+ * Fixed templates only, keyed on the program and its verb — no model, no
+ * scoring, nothing that could decide anything. This module never influences a
+ * verdict; it only words one. A program the grammar does not know is reported
+ * as exactly that ("Runs `foo bar`"), never guessed. Pure: no I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitCommandSteps = splitCommandSteps;
+exports.describeShellCommand = describeShellCommand;
+exports.describeShellCommandLines = describeShellCommandLines;
+const MAX_STEPS = 14;
+const MAX_LINE = 220;
+/** Quote-aware split on `;`, `&&`, `||`, newlines. Pipes stay inside a step. */
+function splitCommandSteps(command) {
+    const steps = [];
+    let current = '';
+    let quote = null;
+    let depth = 0;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            else if (ch === '\\' && quote === '"' && i + 1 < command.length)
+                current += command[++i];
+            else if (ch === '`' && quote === '"' && i + 1 < command.length)
+                current += command[++i];
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '{' || ch === '(')
+            depth++;
+        if (ch === '}' || ch === ')')
+            depth = Math.max(0, depth - 1);
+        const sep = depth === 0 && (ch === '\n' || ch === ';' || ((ch === '&' || ch === '|') && command[i + 1] === ch));
+        if (sep) {
+            if (ch === '&' || ch === '|')
+                i++;
+            steps.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    steps.push(current);
+    return steps.map(step => step.trim()).filter(Boolean);
+}
+/** Tokens with quotes stripped; `--flag=value` kept whole. */
+function tokens(segment) {
+    const out = segment.match(/"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]+/g) || [];
+    return out.map(token => token.replace(/^["']|["']$/g, ''));
+}
+function shortValue(value, max = 80) {
+    const text = value.replace(/\s+/g, ' ').trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function bucketOf(uri) {
+    const m = /^(?:gs|s3|az):\/\/([^/\s]+)/i.exec(uri);
+    return m ? m[1] : uri;
+}
+function isStorageUri(token) {
+    return /^(?:gs|s3|az):\/\//i.test(token);
+}
+function unquote(value) {
+    return value.replace(/^["']|["']$/g, '');
+}
+function flagValue(toks, name) {
+    for (let i = 0; i < toks.length; i++) {
+        if (toks[i] === name && toks[i + 1] && !toks[i + 1].startsWith('-'))
+            return unquote(toks[i + 1]);
+        if (toks[i].startsWith(`${name}=`))
+            return unquote(toks[i].slice(name.length + 1));
+    }
+    return undefined;
+}
+function operandsAfter(toks, from) {
+    const out = [];
+    for (let i = from; i < toks.length; i++) {
+        const token = toks[i];
+        if (token.startsWith('-')) {
+            // `--flag value` (no `=`): skip the value unless it is clearly an operand
+            if (!token.includes('=') && toks[i + 1] && !toks[i + 1].startsWith('-') && !isStorageUri(toks[i + 1]) && !/^\$/.test(toks[i + 1]))
+                i++;
+            continue;
+        }
+        if (/^\d?>&?\d?$/.test(token) || /^[<>]+/.test(token))
+            break; // redirection
+        out.push(token);
+    }
+    return out;
+}
+/** Product names for the first gcloud group word, as Google writes them. */
+const GCLOUD_SERVICE_NAMES = {
+    firestore: 'Firestore', storage: 'Cloud Storage', run: 'Cloud Run', compute: 'Compute Engine', sql: 'Cloud SQL', pubsub: 'Pub/Sub',
+    secrets: 'Secret Manager', iam: 'IAM', projects: 'project', functions: 'Cloud Functions', container: 'GKE', logging: 'Cloud Logging',
+    artifacts: 'Artifact Registry', scheduler: 'Cloud Scheduler', tasks: 'Cloud Tasks', kms: 'Cloud KMS', builds: 'Cloud Build', auth: 'auth', config: 'config',
+};
+const GCLOUD_READ = /^(?:describe|list|ls|get-iam-policy|get-value|get-ancestors|read|check|versions)$/;
+const GCLOUD_WRITE = /^(?:create|update|patch|replace|enable|disable|deploy|apply|start|stop|restart|resume|suspend|scale|promote|migrate|rollback|add-[a-z-]+|remove-[a-z-]+|set-[a-z-]+|unset|clear|activate|revoke|copy)$/;
+function humanVerb(verb) {
+    const map = {
+        describe: 'Reads details of', list: 'Lists', ls: 'Lists', 'get-iam-policy': 'Reads the access policy of', 'get-value': 'Reads the setting',
+        read: 'Reads', check: 'Checks', versions: 'Lists versions of',
+        create: 'Creates', update: 'Updates', patch: 'Updates', replace: 'Replaces', enable: 'Enables', disable: 'Disables', deploy: 'Deploys',
+        apply: 'Applies', start: 'Starts', stop: 'Stops', restart: 'Restarts', resume: 'Resumes', suspend: 'Suspends', scale: 'Scales',
+        promote: 'Promotes', migrate: 'Migrates', rollback: 'Rolls back', unset: 'Unsets', clear: 'Clears', activate: 'Activates', revoke: 'Revokes', copy: 'Copies',
+        delete: 'Deletes',
+    };
+    if (map[verb])
+        return map[verb];
+    if (/^add-iam-policy-binding$/.test(verb))
+        return 'Grants a role on';
+    if (/^remove-iam-policy-binding$/.test(verb))
+        return 'Removes a role from';
+    if (/^add-/.test(verb))
+        return `Adds ${verb.slice(4).replace(/-/g, ' ')} to`;
+    if (/^remove-/.test(verb))
+        return `Removes ${verb.slice(7).replace(/-/g, ' ')} from`;
+    if (/^set-/.test(verb))
+        return `Sets ${verb.slice(4).replace(/-/g, ' ')} on`;
+    return `Runs \`${verb}\` on`;
+}
+function describeGcloud(toks) {
+    let i = 1;
+    while (i < toks.length && toks[i].startsWith('-'))
+        i++;
+    if (/^(?:alpha|beta)$/.test(toks[i] || ''))
+        i++;
+    const groups = [];
+    let verb;
+    for (; i < toks.length; i++) {
+        const token = toks[i];
+        if (token.startsWith('-'))
+            continue;
+        if (GCLOUD_READ.test(token) || GCLOUD_WRITE.test(token) || token === 'delete' || /^(?:export|import|cp|rsync|mv|cat|rm|login|print-access-token|print-identity-token|run|exec|ssh|scp)$/.test(token)) {
+            verb = token;
+            i++;
+            break;
+        }
+        if (!/^[a-z][a-z0-9-]*$/.test(token))
+            break;
+        groups.push(token);
+    }
+    const project = flagValue(toks, '--project');
+    const where = project ? ` in project ${project}` : '';
+    const ops = verb ? operandsAfter(toks, i) : [];
+    const resource = groups.map((group, index) => (index === 0 && GCLOUD_SERVICE_NAMES[group] ? GCLOUD_SERVICE_NAMES[group] : group)).join(' ');
+    const first = ops[0];
+    const isVar = (value) => Boolean(value && /^\$/.test(value));
+    const place = (value) => (isStorageUri(value) ? `storage bucket ${bucketOf(value)}` : isVar(value) ? `the location in ${value}` : shortValue(value, 60));
+    const named = (value) => (value ? (isStorageUri(value) ? `storage bucket ${bucketOf(value)}` : `${resource || 'resource'} ${shortValue(value, 60)}`) : resource || 'resources');
+    if (!verb)
+        return groups.length ? `Runs \`gcloud ${groups.join(' ')}\`${where}` : 'Runs `gcloud`';
+    if (verb === 'export' && first)
+        return `Exports ${resource} data${project ? ` from project ${project}` : ''} to ${place(first)}`;
+    if (verb === 'import' && first)
+        return `Imports ${resource} data${project ? ` into project ${project}` : ''} from ${place(first)}`;
+    if ((verb === 'cp' || verb === 'rsync' || verb === 'mv') && ops.length >= 2) {
+        const last = ops[ops.length - 1];
+        const src = ops.slice(0, -1).join(', ');
+        if (isStorageUri(last) && !isStorageUri(ops[0]))
+            return `Uploads ${shortValue(src, 60)} to storage bucket ${bucketOf(last)}`;
+        if (isStorageUri(ops[0]) && !isStorageUri(last))
+            return `Downloads from storage bucket ${bucketOf(ops[0])} to ${shortValue(last, 60)}`;
+        return `Copies ${shortValue(src, 60)} to ${shortValue(last, 60)}`;
+    }
+    if (verb === 'cat' && first)
+        return `Reads the contents of ${isStorageUri(first) ? `an object in storage bucket ${bucketOf(first)}` : shortValue(first, 60)}`;
+    if (verb === 'rm')
+        return `Deletes ${named(first)}`;
+    if (/^print-(?:access|identity)-token$/.test(verb))
+        return 'Prints a cloud access token to the terminal';
+    if (verb === 'login')
+        return 'Signs in to Google Cloud';
+    if (verb === 'add-iam-policy-binding' || verb === 'remove-iam-policy-binding') {
+        const role = flagValue(toks, '--role');
+        const member = flagValue(toks, '--member');
+        const who = member ? shortValue(member.replace(/^(?:serviceAccount|user|group):/i, ''), 70) : 'a principal';
+        return `${verb.startsWith('add') ? 'Grants' : 'Removes'} ${role ? `role ${role}` : 'a role'} ${verb.startsWith('add') ? 'to' : 'from'} ${who} on ${named(first)}${where}`;
+    }
+    if (verb === 'delete')
+        return `Deletes ${named(first)}${where}`;
+    return `${humanVerb(verb)} ${named(first)}${where}`;
+}
+function describeTransfer(program, toks) {
+    const ops = operandsAfter(toks, program === 'aws' ? 3 : /^gsutil$/i.test(program) ? (toks[1] === '-m' ? 3 : 2) : 1);
+    if (ops.length < 2)
+        return null;
+    const last = ops[ops.length - 1];
+    const src = ops.slice(0, -1).join(', ');
+    const remote = (value) => isStorageUri(value) || /^[\w.-]+@[\w.-]+:/.test(value) || /^[\w.-]+:(?:[/~]|$)/.test(value);
+    if (remote(last) && !remote(ops[0]))
+        return `Uploads ${shortValue(src, 60)} to ${isStorageUri(last) ? `storage bucket ${bucketOf(last)}` : shortValue(last, 60)}`;
+    if (remote(ops[0]) && !remote(last))
+        return `Downloads from ${isStorageUri(ops[0]) ? `storage bucket ${bucketOf(ops[0])}` : shortValue(ops[0], 60)} to ${shortValue(last, 60)}`;
+    return `Copies ${shortValue(src, 60)} to ${shortValue(last, 60)}`;
+}
+function hostOf(text) {
+    const m = /https?:\/\/([^/\s"'<>`]+)/i.exec(text);
+    return m ? m[1] : undefined;
+}
+function describeHttp(program, segment, toks) {
+    const host = hostOf(segment);
+    const method = (/(?:\s-X|\s--request|\s-Method)[\s=]+["']?([A-Za-z]+)/i.exec(segment)?.[1] || '').toUpperCase();
+    const body = /\s(?:-d|--data(?:-raw|-binary|-urlencode)?|-F|--form|-T|--upload-file|--json|-Body|-InFile)\b/i.test(segment);
+    const target = host ? ` ${host}` : toks[1] ? ` ${shortValue(toks[1], 60)}` : '';
+    if (method && method !== 'GET' || body)
+        return `Sends ${method && method !== 'GET' ? `a ${method} request` : 'data'} to${target}`;
+    return `Fetches${target} over HTTP`;
+}
+function describePipeTail(stages) {
+    if (stages.length === 0)
+        return '';
+    const interpreter = stages.some(stage => /^\s*(?:sudo\s+)?(?:(?:ba|z|da|k)?sh|pwsh|powershell(?:\.exe)?|python3?|node|perl|ruby)\b/i.test(stage) || /\bInvoke-Expression\b|\biex\b/i.test(stage));
+    if (interpreter)
+        return ', then RUNS the output as code';
+    const writesFile = stages.some(stage => /^\s*(?:Out-File|Set-Content|Add-Content|tee)\b/i.test(stage));
+    if (writesFile)
+        return ', and writes the output to a file';
+    return '';
+}
+function describeOne(segmentIn) {
+    const segment = segmentIn.trim();
+    const [head, ...pipe] = splitPipe(segment);
+    const tail = describePipeTail(pipe);
+    const step = (text, known = true) => ({ segment, text: shortValue(`${text}${tail}`, MAX_LINE), known });
+    // Redirection — `> file` / `>> file` — judged on the command words, never inside a quoted string.
+    const maskedHead = head.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""');
+    const redirectTo = /(?:^|[^>0-9-])>{1,2}\s*([^\s&|;]+)/.exec(maskedHead)?.[1];
+    const redirectNote = redirectTo && !/^\$null$|^nul$|^\/dev\/null$|^&\d$/i.test(redirectTo) ? `, writing the output to ${shortValue(redirectTo, 40)}` : '';
+    // `if (…) { body }` / `else { body }`: the body is what runs; say so conditionally.
+    const block = /^(if|elseif|else|try|catch|finally|foreach|while|for)\b[^{]*\{(.*)\}\s*$/is.exec(head);
+    if (block) {
+        const bodySteps = splitCommandSteps(block[2]).map(part => describeOne(part).text);
+        const lead = /^(?:if|elseif)$/i.test(block[1]) ? 'If the condition holds' : /^else$/i.test(block[1]) ? 'Otherwise' : /^(?:try)$/i.test(block[1]) ? 'Tries' : /^(?:catch)$/i.test(block[1]) ? 'On error' : /^finally$/i.test(block[1]) ? 'Finally' : 'For each item';
+        return { segment, text: shortValue(`${lead}: ${bodySteps.join(' · ') || 'nothing'}${tail}`, MAX_LINE), known: true };
+    }
+    // Assignment: `$x = <cmd>` / `$x=<cmd>` / `NAME=value`
+    const assign = /^\$([\w:]+)\s*=\s*(.+)$/s.exec(head) || /^([A-Za-z_]\w*)=(.+)$/s.exec(head);
+    if (assign) {
+        const name = assign[1];
+        const rhs = assign[2].trim();
+        if (/^\$ErrorActionPreference$|^\$ProgressPreference$|^\$VerbosePreference$|^\$WarningPreference$|^\$InformationPreference$/i.test(`$${name}`))
+            return step('Sets a PowerShell error/output preference');
+        // A quoted string (interpolating or not), a number, a boolean, a literal array / hashtable.
+        const literal = /^(?:"(?:[^"\\`]|\\.|`.)*"|'[^']*'|\d+|\$true|\$false|@\([^)]*\)|@\{[^}]*\})$/s.test(rhs);
+        if (literal) {
+            const bare = rhs.replace(/^["']|["']$/g, '');
+            const storage = /(?:gs|s3|az):\/\/([^/\s"'$]+)/i.exec(bare);
+            if (storage)
+                return step(`Sets variable ${name} to a location in storage bucket ${storage[1]}`);
+            const interpolates = /\$\w+|\$\{|\$\(/.test(bare);
+            return step(`Sets variable ${name}${interpolates ? ' from other values' : ` to ${shortValue(bare, 60)}`}`);
+        }
+        const inner = rhs.replace(/^\(\s*/, '').replace(/\)\s*(?:\.\w+\(\))*$/, '');
+        const innerStep = describeOne(inner);
+        return { segment, text: shortValue(`Stores in ${name}: ${innerStep.text.charAt(0).toLowerCase()}${innerStep.text.slice(1)}${tail}`, MAX_LINE), known: innerStep.known };
+    }
+    const toks = tokens(head);
+    if (toks.length === 0)
+        return step('(empty)', false);
+    let p = 0;
+    while (p < toks.length && (/^[A-Za-z_]\w*=/.test(toks[p]) || /^(?:sudo|time|nohup|command|builtin|exec|nice|env)$/i.test(toks[p])))
+        p++;
+    const programToken = toks[p] || '';
+    const program = programToken.replace(/^.*[\\/]/, '').replace(/\.(?:exe|cmd|bat)$/i, '').toLowerCase();
+    const rest = toks.slice(p);
+    // Control-flow / block structure
+    if (/^(?:if|elseif|else|try|catch|finally|foreach|for|while|switch|function|param|do|done|fi|then|\}|\{|\)|\()$/i.test(program) || /^[{}()]+$/.test(head))
+        return step('Script structure (no action by itself)');
+    switch (program) {
+        case 'start-sleep':
+        case 'sleep': {
+            const secs = flagValue(rest, '-Seconds') || flagValue(rest, '-s') || rest[1];
+            return step(`Waits ${secs ? `${secs} seconds` : 'a moment'}`);
+        }
+        case 'write-host':
+        case 'write-output':
+        case 'echo':
+        case 'printf':
+        case 'write-verbose':
+        case 'write-warning':
+            return step(`Prints a message${redirectNote}`);
+        case 'cd':
+        case 'set-location':
+        case 'sl':
+        case 'pushd':
+        case 'push-location':
+            return step(`Changes directory to ${shortValue(rest[1] || '~', 60)}`);
+        case 'exit':
+        case 'return': return step('Ends the script');
+        case 'gcloud': {
+            const text = describeGcloud(rest);
+            return text ? step(`${text}${redirectNote}`) : step(`Runs \`gcloud\``, false);
+        }
+        case 'gsutil': {
+            if (/^(?:cp|rsync|mv)$/.test(rest[1] === '-m' ? rest[2] : rest[1])) {
+                const t = describeTransfer('gsutil', rest);
+                if (t)
+                    return step(t);
+            }
+            if (rest[1] === 'ls')
+                return step(`Lists ${rest[2] && isStorageUri(rest[2]) ? `storage bucket ${bucketOf(rest[2])}` : 'storage buckets'}`);
+            if (rest[1] === 'rm')
+                return step(`Deletes objects in storage bucket ${rest[2] ? bucketOf(rest[2]) : ''}`);
+            return step(`Runs \`gsutil ${rest[1] || ''}\``, false);
+        }
+        case 'aws': {
+            if (rest[1] === 's3' && /^(?:cp|sync|mv)$/.test(rest[2] || '')) {
+                const t = describeTransfer('aws', rest);
+                if (t)
+                    return step(t);
+            }
+            if (rest[1] === 's3' && rest[2] === 'ls')
+                return step('Lists S3 buckets or objects');
+            if (/^(?:describe|list|get)-/.test(rest[2] || ''))
+                return step(`Reads ${rest[1]} ${(rest[2] || '').replace(/^(?:describe|list|get)-/, '').replace(/-/g, ' ')}`);
+            if (/^(?:delete|terminate)-/.test(rest[2] || ''))
+                return step(`Deletes ${rest[1]} ${(rest[2] || '').replace(/^(?:delete|terminate)-/, '').replace(/-/g, ' ')}`);
+            if (/^(?:create|update|put|register)-/.test(rest[2] || ''))
+                return step(`Changes ${rest[1]} ${(rest[2] || '').replace(/-/g, ' ')}`);
+            return step(`Runs \`aws ${[rest[1], rest[2]].filter(Boolean).join(' ')}\``, false);
+        }
+        case 'kubectl': {
+            const verb = rest[1] || '';
+            if (/^(?:get|describe|logs|top|explain|api-resources|version)$/.test(verb))
+                return step(`Reads Kubernetes ${rest[2] || verb}${flagValue(rest, '-n') || flagValue(rest, '--namespace') ? ` in namespace ${flagValue(rest, '-n') || flagValue(rest, '--namespace')}` : ''}`);
+            if (verb === 'delete')
+                return step(`Deletes Kubernetes ${rest.slice(2).filter(t => !t.startsWith('-')).join(' ')}`);
+            if (/^(?:apply|create|patch|scale|rollout|set|label|annotate|edit|replace)$/.test(verb))
+                return step(`Changes Kubernetes resources (${verb})`);
+            if (verb === 'exec')
+                return step('Runs a command inside a Kubernetes pod', false);
+            return step(`Runs \`kubectl ${verb}\``, false);
+        }
+        case 'git': {
+            const sub = rest.find((t, idx) => idx > 0 && !t.startsWith('-') && !/^(?:-c|-C)$/.test(rest[idx - 1] || '')) || '';
+            const map = {
+                status: 'Reads git status', diff: 'Shows git differences', log: 'Reads git history', show: 'Shows a git object', blame: 'Reads git blame',
+                fetch: 'Fetches from the git remote', pull: 'Pulls from the git remote', clone: 'Clones a git repository',
+                add: 'Stages files in git', commit: 'Creates a git commit', push: 'Pushes commits to the git remote', checkout: 'Switches git branch or files',
+                switch: 'Switches git branch', branch: 'Reads or changes git branches', stash: 'Stashes working changes', merge: 'Merges git branches',
+                rebase: 'Rebases git history', reset: 'Resets git state', clean: 'Removes untracked files', tag: 'Reads or creates git tags', remote: 'Reads or changes git remotes',
+            };
+            return step(map[sub] || `Runs \`git ${sub}\``, Boolean(map[sub]));
+        }
+        case 'gh': {
+            const sub = rest.slice(1, 3).filter(t => !t.startsWith('-')).join(' ');
+            if (/\b(?:view|list|status|checks|diff)\b/.test(sub))
+                return step(`Reads GitHub ${sub.split(' ')[0]}`);
+            if (/^api\b/.test(sub))
+                return step(/\s-X\s+(?!GET)|--method\s+(?!GET)|\s-[fF]\s|--field|--input/i.test(head) ? 'Writes through the GitHub API' : 'Reads from the GitHub API');
+            if (/\b(?:create|edit|merge|close|delete|comment)\b/.test(sub))
+                return step(`Changes GitHub ${sub.split(' ')[0]} (${sub.split(' ')[1]})`);
+            if (/^auth token\b/.test(sub))
+                return step('Prints the GitHub token');
+            return step(`Runs \`gh ${sub}\``, false);
+        }
+        case 'npm':
+        case 'pnpm':
+        case 'yarn': {
+            const sub = rest[1] || '';
+            if (sub === 'run')
+                return step(`Runs the ${program} script "${rest[2] || ''}"`);
+            if (/^(?:test|t)$/.test(sub))
+                return step(`Runs ${program} tests`);
+            if (/^(?:install|ci|i|add)$/.test(sub))
+                return step(`Installs ${program} packages`);
+            if (/^(?:publish)$/.test(sub))
+                return step(`Publishes an ${program} package`);
+            if (/^(?:view|ls|list|outdated|--version|-v|version)$/.test(sub))
+                return step(`Reads ${program} package info`);
+            if (/^(?:build|typecheck|lint|dev|start)$/.test(sub))
+                return step(`Runs the ${program} script "${sub}"`);
+            return step(`Runs \`${program} ${sub}\``, false);
+        }
+        case 'node':
+        case 'npx':
+        case 'python':
+        case 'python3':
+        case 'tsx':
+        case 'ts-node':
+            return step(`Runs ${program} ${rest[1] ? `(${shortValue(rest.slice(1).join(' '), 60)})` : ''}`, false);
+        case 'curl':
+        case 'wget':
+        case 'invoke-webrequest':
+        case 'iwr':
+        case 'invoke-restmethod':
+        case 'irm':
+            return step(describeHttp(program, head, rest));
+        case 'rm':
+        case 'remove-item':
+        case 'ri':
+        case 'del':
+        case 'erase':
+        case 'rmdir':
+        case 'rd': {
+            const targets = rest.slice(1).filter(t => !t.startsWith('-'));
+            const recursive = /\s-r|\s-recurse|\s-rf|\s-fr/i.test(head) || program === 'rmdir' || program === 'rd';
+            return step(`Deletes ${recursive ? 'the folder ' : ''}${shortValue(targets.join(', ') || 'files', 60)}`);
+        }
+        case 'cp':
+        case 'copy':
+        case 'copy-item':
+        case 'cpi':
+        case 'mv':
+        case 'move':
+        case 'move-item':
+        case 'mi':
+        case 'ren':
+        case 'rename-item': {
+            const targets = rest.slice(1).filter(t => !t.startsWith('-'));
+            return step(`${/^(?:mv|move|move-item|mi|ren|rename-item)$/.test(program) ? 'Moves' : 'Copies'} ${shortValue(targets[0] || '', 40)} to ${shortValue(targets[targets.length - 1] || '', 40)}`);
+        }
+        case 'mkdir':
+        case 'new-item':
+        case 'ni':
+        case 'touch': return step(`Creates ${shortValue(rest.slice(1).filter(t => !t.startsWith('-')).join(', '), 60)}`);
+        case 'cat':
+        case 'get-content':
+        case 'gc':
+        case 'type':
+        case 'head':
+        case 'tail':
+        case 'less':
+        case 'more':
+            return step(`Reads the file ${shortValue(rest.slice(1).filter(t => !t.startsWith('-'))[0] || '', 60)}${redirectNote}`);
+        case 'ls':
+        case 'dir':
+        case 'get-childitem':
+        case 'gci':
+        case 'tree':
+        case 'find':
+        case 'fd':
+            return step(`Lists files${rest[1] && !rest[1].startsWith('-') ? ` in ${shortValue(rest[1], 60)}` : ''}`);
+        case 'grep':
+        case 'rg':
+        case 'select-string':
+        case 'sls':
+        case 'ag':
+        case 'findstr':
+            return step('Searches text in files');
+        case 'test-path':
+        case 'get-item':
+        case 'gi':
+        case 'resolve-path': return step(`Checks ${shortValue(rest[1] || 'a path', 60)}`);
+        case 'get-cimInstance':
+        case 'get-ciminstance':
+        case 'get-process':
+        case 'ps':
+        case 'tasklist': return step('Reads running processes');
+        case 'stop-process':
+        case 'kill':
+        case 'taskkill': return step(`Stops a process${rest.some(t => /^-Id$/i.test(t)) ? ` (pid ${flagValue(rest, '-Id')})` : ''}`);
+        case 'docker': {
+            const sub = rest[1] || '';
+            if (/^(?:ps|images|logs|inspect|version|info)$/.test(sub))
+                return step(`Reads Docker ${sub}`);
+            if (/^(?:build|push|pull|run|compose|exec|rm|rmi|system)$/.test(sub))
+                return step(`Runs \`docker ${sub}${rest[2] && !rest[2].startsWith('-') ? ` ${rest[2]}` : ''}\``, sub !== 'exec' && sub !== 'run');
+            return step(`Runs \`docker ${sub}\``, false);
+        }
+        case 'terraform': {
+            const sub = rest[1] || '';
+            if (/^(?:plan|validate|fmt|show|output|state)$/.test(sub))
+                return step(`Reads Terraform ${sub}`);
+            if (sub === 'apply')
+                return step('Applies Terraform changes to infrastructure');
+            if (sub === 'destroy')
+                return step('DESTROYS Terraform-managed infrastructure');
+            return step(`Runs \`terraform ${sub}\``, false);
+        }
+        case 'firebase': return step(`Runs \`firebase ${rest[1] || ''}\``, /^(?:deploy)$/.test(rest[1] || ''));
+        case 'ssh':
+        case 'scp':
+        case 'rsync':
+        case 'sftp': {
+            if (program !== 'ssh') {
+                const t = describeTransfer(program, rest);
+                if (t)
+                    return step(t);
+            }
+            return step(`Connects to ${shortValue(rest.find((t, idx) => idx > 0 && !t.startsWith('-')) || 'a remote host', 60)} over SSH`, false);
+        }
+        case 'psql':
+        case 'mysql':
+        case 'sqlcmd':
+        case 'sqlite3':
+        case 'mongosh': {
+            const verb = /\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|GRANT|REVOKE)\b/i.exec(head)?.[1]?.toUpperCase();
+            return step(verb ? `Runs a database ${verb}` : `Opens a ${program} database session`, Boolean(verb));
+        }
+        case 'select-object':
+        case 'select':
+        case 'format-table':
+        case 'ft':
+        case 'format-list':
+        case 'fl':
+        case 'out-string':
+        case 'convertfrom-json':
+        case 'convertto-json':
+        case 'sort-object':
+        case 'sort':
+        case 'where-object':
+        case 'where':
+        case 'foreach-object':
+        case 'foreach':
+        case 'measure-object':
+        case 'out-null':
+            return step('Formats or filters output');
+        case 'invoke-expression':
+        case 'iex': return step('RUNS a string as code', false);
+        default:
+            if (/^\$/.test(programToken))
+                return step(pipe.length ? `Uses ${shortValue(programToken, 40)}${tail}` : `Reads variable ${shortValue(programToken, 40)}`, false);
+            return step(`Runs \`${shortValue([program, rest[1]].filter(t => t && !t.startsWith('-')).join(' '), 50)}\``, false);
+    }
+}
+/** Split one step on top-level `|` (quote-aware). */
+function splitPipe(segment) {
+    const parts = [];
+    let current = '';
+    let quote = null;
+    let depth = 0;
+    for (let i = 0; i < segment.length; i++) {
+        const ch = segment[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '{' || ch === '(')
+            depth++;
+        if (ch === '}' || ch === ')')
+            depth = Math.max(0, depth - 1);
+        if (ch === '|' && depth === 0 && segment[i + 1] !== '|') {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts.map(part => part.trim()).filter(Boolean);
+}
+/**
+ * `$prefix = "gs://bucket/…"` two steps earlier, then `export $prefix`: say the
+ * bucket, not the variable. Only literal storage locations are resolved — a
+ * value computed from a command stays "the location in $var".
+ */
+function resolveStorageVariables(steps) {
+    const buckets = new Map();
+    return steps.map(step => {
+        const assign = /^\$?([\w:]+)\s*=\s*(?:"|')?((?:gs|s3|az):\/\/([^/\s"'$]+))/i.exec(step.segment);
+        if (assign)
+            buckets.set(assign[1], assign[3]);
+        let text = step.text;
+        for (const [name, bucket] of buckets)
+            text = text.replace(new RegExp(`the location in \\$${name}\\b`, 'g'), `storage bucket ${bucket}`);
+        return { ...step, text };
+    });
+}
+/** One plain-words line per step, in order. */
+function describeShellCommand(command) {
+    const steps = splitCommandSteps(command);
+    const out = resolveStorageVariables(steps.slice(0, MAX_STEPS).map(segment => {
+        try {
+            return describeOne(segment);
+        }
+        catch {
+            return { segment, text: 'Runs a command the grammar does not recognise', known: false };
+        }
+    }));
+    if (steps.length > MAX_STEPS)
+        out.push({ segment: '', text: `… and ${steps.length - MAX_STEPS} more step${steps.length - MAX_STEPS === 1 ? '' : 's'}`, known: false });
+    return out;
+}
+/** The step lines as the explanation prints them (`- …`). */
+function describeShellCommandLines(command) {
+    return describeShellCommand(command).map(step => step.text);
+}

package/dist/commands/workloadProtect.d.ts

@@ -63,6 +63,13 @@ export interface WorkloadProtectArgs {
     httpGateway?: string;
     /** Agent name for API-destination attribution (default: the workload name). */
     agentName?: string;
+    /**
+     * The connection this workload was protected THROUGH — the console section
+     * it files under (heroku | kubernetes | aws | gcp). Set by the snippet the
+     * console generated (FCD_ENROLLED_VIA) or detected from the platform; never
+     * derived from the cloud the container happens to run on.
+     */
+    enrolledVia?: string;
 }
 export interface WorkloadContext {
     kind: string;
@@ -70,7 +77,10 @@ export interface WorkloadContext {
     environment?: string;
     instanceId?: string;
     image?: string;
+    /** Connection implied by the platform's own env (Heroku dyno, Cloud Run, Lambda, Kubernetes). */
+    enrolledVia?: string;
 }
+export declare function resolveEnrolledVia(explicit: string | undefined, env: NodeJS.ProcessEnv, detected: string | undefined): string | undefined;
 /**
  * Detect the workload from standard platform env vars. Explicit flags /
  * FCD_WORKLOAD_* always win; detection only fills the gaps.