fullcourtdefense-cli 1.35.10 → 1.36.2

package/dist/cloudGrant.d.ts

@@ -0,0 +1,46 @@
+import { type AwsDefaults, type AzDefaults, type KubeDefaults, type TfDefaults } from './cloudGrantTools';
+export type CloudGrantRefusal = 'delete' | 'permissions' | 'protected' | 'environment_unread' | 'target_unknown';
+/** Resolves the project a gcloud use falls back to (env / active configuration). `null` = unknown. */
+export type DefaultProject = (configuration: string | undefined) => string | null;
+/**
+ * The cloud entries for one shell line: sorted, unique, one per cloud CLI use.
+ * `uses` are the program uses the grant scanner found (`scanShellPrograms`).
+ * Empty when the line runs no cloud CLI. `tools` are the aws / kube defaults
+ * (tests pass fixtures); omitted = read from the caller's environment.
+ * `destinationBound`: the grant already binds where data goes (`unreadTarget`).
+ */
+export declare function cloudGrantEntries(command: string, uses: ReadonlyArray<{
+    name: string;
+    text: string;
+}>, defaultProject: DefaultProject, tools?: {
+    aws?: AwsDefaults;
+    kube?: KubeDefaults;
+    az?: AzDefaults;
+    tf?: TfDefaults;
+    destinationBound?: boolean;
+    cwd?: string;
+}): string[];
+/** Why a line with these entries cannot carry an Always allow; undefined when it can. */
+export declare function cloudGrantRefusal(entries: readonly string[] | undefined): CloudGrantRefusal | undefined;
+/** Every live entry must be in the grant. A grant recorded before entries existed covers no cloud line. */
+export declare function cloudGrantCovers(granted: readonly string[] | undefined, live: readonly string[] | undefined): boolean;
+/** One short line for the dialog when Always allow is not offered. */
+export declare function describeCloudRefusal(refusal: CloudGrantRefusal, entries?: readonly string[]): string;
+/** How / Where in plain words, for the dialog and the grant list. */
+export declare function describeCloudEntries(entries: readonly string[]): {
+    how: string;
+    where: string;
+};
+/**
+ * The environment names in cloud entries — gcloud projects, aws profiles,
+ * kube contexts — for the dialog's by-name environment tag. The tag itself is
+ * the dialog's one helper; this only says which names it applies to.
+ */
+export declare function cloudEntryEnvironmentNames(entries: readonly string[]): string[];
+/**
+ * The project gcloud uses when the command names none: CLOUDSDK_CORE_PROJECT,
+ * else `[core] project` of the active configuration (`CLOUDSDK_ACTIVE_CONFIG_NAME`,
+ * else the `active_config` file, else `default`) under CLOUDSDK_CONFIG or the
+ * per-user gcloud directory. Any read error or odd value = null (unknown).
+ */
+export declare function activeGcloudProject(configuration?: string, env?: NodeJS.ProcessEnv): string | null;

package/dist/cloudGrant.js

@@ -0,0 +1,420 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloudGrantEntries = cloudGrantEntries;
+exports.cloudGrantRefusal = cloudGrantRefusal;
+exports.cloudGrantCovers = cloudGrantCovers;
+exports.describeCloudRefusal = describeCloudRefusal;
+exports.describeCloudEntries = describeCloudEntries;
+exports.cloudEntryEnvironmentNames = cloudEntryEnvironmentNames;
+exports.activeGcloudProject = activeGcloudProject;
+/**
+ * "Always allow" for a cloud CLI covers WHAT + HOW + WHERE (#1747).
+ *
+ * A shell grant used to remember only the programs on the line, so Always
+ * allow on `gcloud run deploy --project acme-staging` also covered
+ * `gcloud run services delete … --project acme-prod` under the same rule.
+ * Each gcloud use on the line now adds one entry `gcloud|<how>|<where>`:
+ *
+ *   how    read | change | permissions | delete — from the verb, with the
+ *          engine's gcloud grammar (`gcloudVerbWord`, `GCLOUD_*_VERB_RE`).
+ *          A verb that grammar does not know is bound to its exact command
+ *          path (`cmd:builds submit`), never to a class.
+ *   where  `project=<id>` — `--project`, a `projects/<id>/…` resource, the
+ *          `gcloud projects <verb> <id>` operand, else CLOUDSDK_CORE_PROJECT,
+ *          else the active gcloud configuration; `?` when it cannot be read.
+ *          Account-level groups (`auth`, `config`, …) act on no project and
+ *          add no entry; a `config` change on the line makes every default `?`.
+ *
+ * aws and kubectl / oc / helm use the same format with their own how / where
+ * (`cloudGrantTools.ts`: profile + region, context + namespace). Every other
+ * use that acts outside the machine on a target not read yet (az, terraform,
+ * `git push`, psql, ssh, vault, a `curl` POST, … — `grantTargets.ts`) adds
+ * `<label>|?|?`: no Always allow for it.
+ *
+ * Deletes, permission changes and an unreadable target get no Always allow
+ * (`cloudGrantRefusal`). Grants match by inclusion: every live entry must be
+ * in the grant. Deterministic words and flags only; the I/O is reading the
+ * tools' configuration files (`activeGcloudProject`, `awsDefaultsFrom`,
+ * `kubeDefaultsFrom`), never running a CLI.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const callerEnv_1 = require("./callerEnv");
+const cloudGrantTools_1 = require("./cloudGrantTools");
+const credentialGrant_1 = require("./credentialGrant");
+const grantTargets_1 = require("./grantTargets");
+const shellQuoteMask_1 = require("./shellQuoteMask");
+let grammar;
+/** The engine is only needed when a line runs gcloud; the ask-dialog process never loads it. */
+function gcloudGrammar() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return grammar || (grammar = require('./actionPolicyEngine'));
+}
+const KUBE_TOOLS = new Set(['kubectl', 'oc', 'helm']);
+/** The flag a person adds so the target can be read, per tool. */
+const TARGET_HINT = {
+    gcloud: 'Always allow needs the project on the command: add --project.',
+    aws: 'Always allow needs the AWS profile and region on the command: add --profile and --region.',
+    kubectl: 'Always allow needs the cluster on the command: add --context and --namespace.',
+    oc: 'Always allow needs the cluster on the command: add --context and --namespace.',
+    helm: 'Always allow needs the cluster on the command: add --kube-context and --namespace.',
+    git: 'Always allow needs the remote and branch on the command: git push <remote> <branch>.',
+    az: 'Always allow needs a subscription this machine knows (its ID, or a name listed by az account list) and the resource group: add --subscription and -g.',
+    terraform: 'Always allow needs the terraform directory and workspace: use -chdir and -var-file (not -var) from a known folder.',
+    tofu: 'Always allow needs the tofu directory and workspace: use -chdir and -var-file (not -var) from a known folder.',
+    terragrunt: 'Always allow needs the terragrunt directory and workspace: one module, --working-dir, from a known folder.',
+    ssh: 'Always allow needs the host on the command, without -F or a ProxyCommand / HostName override.',
+    scp: 'Always allow needs the host on the command, without -F or a ProxyCommand / HostName override.',
+    sftp: 'Always allow needs the host on the command, without -F or a ProxyCommand / HostName override.',
+    rsync: 'Always allow needs the host on the command and plain ssh as the transport.',
+    psql: 'Always allow needs the database host and name on the command: add -h and -d.',
+    mysql: 'Always allow needs the database host and name on the command: add -h and the database.',
+    mariadb: 'Always allow needs the database host and name on the command: add -h and the database.',
+};
+/** Groups that act on the account or the local SDK, not on a project. */
+const ACCOUNT_GROUPS = new Set(['auth', 'config', 'components', 'info', 'version', 'help', 'topic', 'init', 'survey', 'feedback', 'cheat-sheet']);
+/** Release-track words that sit before the group. */
+const TRACK_WORDS = new Set(['alpha', 'beta', 'preview']);
+/** Command words that remove data although the engine grammar has no verb for them (`storage rm`). */
+const DELETE_WORD_RE = /^(?:rm|purge)$/;
+/** Global flags that take a separate value (`--project acme`); their value is not a command word. */
+const VALUED_GLOBAL_FLAGS = new Set(['--project', '--configuration', '--account', '--billing-project', '--impersonate-service-account', '--format', '--verbosity', '--flags-file', '--region', '--zone', '--filter', '--limit', '--sort-by', '--page-size']);
+const COMMAND_WORD_RE = /^[a-z][a-z0-9-]*$/;
+/** A GCP project id or number, including domain-scoped `example.com:proj`. */
+const PROJECT_ID_RE = /^(?:[a-z][a-z0-9.-]*:)?[a-z0-9][a-z0-9-]{3,62}$/;
+const CONFIG_NAME_RE = /^[a-z][a-z0-9-]*$/;
+/** A word as the grammar reads it: lowercase; a quoted value with spaces or code is no command word. */
+function grammarWord(word) {
+    const bare = (0, credentialGrant_1.unquote)(word);
+    return /^["']/.test(word) && /[\s|;&$`()]/.test(bare) ? '"…"' : bare.toLowerCase();
+}
+/**
+ * Group / command words with their index: up to and including the verb when
+ * the grammar knows it, else up to the first flag once two words are read.
+ */
+function commandPath(words, verb) {
+    const out = [];
+    for (let k = 0; k < words.length && out.length < 6; k++) {
+        const word = words[k];
+        if (word.startsWith('-')) {
+            if (!verb && out.length >= 2)
+                break;
+            if (VALUED_GLOBAL_FLAGS.has(word))
+                k++;
+            continue;
+        }
+        if (!COMMAND_WORD_RE.test(word))
+            break;
+        if (!out.length && TRACK_WORDS.has(word))
+            continue;
+        out.push({ word, at: k });
+        if (word === verb)
+            break;
+    }
+    return out;
+}
+function classify(verb, cmdPath) {
+    const { GCLOUD_READ_VERB_RE, GCLOUD_WRITE_VERB_RE, GCLOUD_DELETE_VERB_RE } = gcloudGrammar();
+    if (verb && GCLOUD_DELETE_VERB_RE.test(verb))
+        return 'delete';
+    if (verb && GCLOUD_READ_VERB_RE.test(verb))
+        return 'read';
+    if (verb && GCLOUD_WRITE_VERB_RE.test(verb))
+        return /iam-policy/.test(verb) || cmdPath.includes('iam') ? 'permissions' : 'change';
+    if (cmdPath.some(word => DELETE_WORD_RE.test(word)))
+        return 'delete';
+    return `cmd:${cmdPath.join(' ') || 'gcloud'}`;
+}
+/** The project this use names itself: flag, resource path or `projects <verb> <id>`. `?` when dynamic or ambiguous. */
+function namedProject(argv, cmdPath, verbAt, vars) {
+    const named = new Set();
+    for (let k = 0; k < argv.length; k++) {
+        const bare = (0, credentialGrant_1.unquote)(argv[k]);
+        // A flags file can set any flag, the project included.
+        if (bare === '--flags-file' || bare.startsWith('--flags-file='))
+            return '?';
+        if (bare !== '--project' && !bare.startsWith('--project='))
+            continue;
+        const value = (0, credentialGrant_1.flagValue)(argv.slice(k, k + 2), ['--project'], vars);
+        if (!value)
+            return '?';
+        named.add(value.toLowerCase());
+    }
+    for (const word of argv) {
+        const bare = (0, credentialGrant_1.unquote)(word);
+        const value = bare.startsWith('-') ? bare.slice(bare.indexOf('=') + 1) : bare;
+        const ref = value.match(/(?:^|\/)projects\/([^/\s]+)/i);
+        if (!ref)
+            continue;
+        if (/[$`(){}%]/.test(ref[1]))
+            return '?';
+        named.add(ref[1].toLowerCase());
+    }
+    if (cmdPath[0] === 'projects' && cmdPath.length === 2) {
+        // `gcloud projects <verb> <id>`: the operand IS the project. Unknown verb = no operand read.
+        const operand = verbAt >= 0 ? argv.slice(verbAt + 1).find(w => !(0, credentialGrant_1.unquote)(w).startsWith('-')) : undefined;
+        if (operand === undefined && verbAt >= 0)
+            return cmdPath[1] === 'list' ? 'account' : '?';
+        if (operand !== undefined) {
+            const bare = (0, credentialGrant_1.unquote)(operand);
+            if (/[$`(){}%]/.test(bare))
+                return '?';
+            named.add(bare.toLowerCase());
+        }
+    }
+    if (named.size > 1)
+        return '?';
+    const only = [...named][0];
+    if (only === undefined)
+        return undefined;
+    return PROJECT_ID_RE.test(only) ? `project=${only}` : '?';
+}
+function readUse(text, dialect, vars) {
+    const argv = (0, cloudGrantTools_1.toolArgv)(text, dialect, ['gcloud']);
+    const words = argv.map(grammarWord);
+    const verb = gcloudGrammar().gcloudVerbWord(['gcloud', ...words].join(' '));
+    const pathWords = commandPath(words, verb);
+    const cmdPath = pathWords.map(p => p.word);
+    const how = classify(verb, cmdPath);
+    const mutatesConfig = (cmdPath[0] === 'config' || cmdPath[0] === 'init') && how !== 'read';
+    // `gcloud --version` / `gcloud help …` names no group: local SDK, no project.
+    if (!cmdPath.length || ACCOUNT_GROUPS.has(cmdPath[0]))
+        return { how, where: 'account', mutatesConfig };
+    const verbAt = verb && pathWords.length && pathWords[pathWords.length - 1].word === verb ? pathWords[pathWords.length - 1].at : -1;
+    const where = namedProject(argv, cmdPath, verbAt, vars);
+    const configuration = (0, credentialGrant_1.flagValue)(argv, ['--configuration'], vars);
+    return { how, where, configuration, mutatesConfig };
+}
+/**
+ * The cloud entries for one shell line: sorted, unique, one per cloud CLI use.
+ * `uses` are the program uses the grant scanner found (`scanShellPrograms`).
+ * Empty when the line runs no cloud CLI. `tools` are the aws / kube defaults
+ * (tests pass fixtures); omitted = read from the caller's environment.
+ * `destinationBound`: the grant already binds where data goes (`unreadTarget`).
+ */
+function cloudGrantEntries(command, uses, defaultProject, tools) {
+    const entries = new Set();
+    const dialect = (0, shellQuoteMask_1.shellDialectOf)(command);
+    const env = (0, callerEnv_1.callerEnv)();
+    for (const use of uses) {
+        const unread = (0, grantTargets_1.unreadTarget)(use.name, (0, cloudGrantTools_1.toolArgv)(use.text, dialect, [use.name]), env, Boolean(tools?.destinationBound));
+        if (unread)
+            entries.add(`${unread.label}|?|?`);
+    }
+    const aws = uses.filter(use => use.name === 'aws');
+    const kube = uses.filter(use => KUBE_TOOLS.has(use.name));
+    const gcloud = uses.filter(use => use.name === 'gcloud');
+    const git = uses.filter(use => use.name === 'git');
+    const az = uses.filter(use => use.name === 'az');
+    const tf = uses.filter(use => (0, cloudGrantTools_1.isTfTool)(use.name));
+    const remote = uses.filter(use => (0, cloudGrantTools_1.isRemoteTool)(use.name));
+    const sql = uses.filter(use => (0, cloudGrantTools_1.isSqlTool)(use.name));
+    if (!aws.length && !kube.length && !gcloud.length && !git.length && !az.length && !tf.length && !remote.length && !sql.length)
+        return [...entries].sort();
+    const vars = (0, credentialGrant_1.lineVars)(command, dialect);
+    const toolUses = [
+        ...(0, cloudGrantTools_1.sqlUses)(sql.map(use => ({ tool: use.name, text: use.text })), command, dialect, vars, env),
+        ...(0, cloudGrantTools_1.remoteUses)(remote.map(use => ({ tool: use.name, text: use.text })), dialect, vars),
+        ...(tf.length ? (0, cloudGrantTools_1.tfUses)(tf.map(use => ({ tool: use.name, text: use.text })), command, dialect, vars, tools?.tf || (0, cloudGrantTools_1.tfDefaultsFrom)(env), tools?.cwd) : []),
+        ...(az.length ? (0, cloudGrantTools_1.azUses)(az.map(use => use.text), command, dialect, vars, tools?.az || (0, cloudGrantTools_1.azDefaultsFrom)(env)) : []),
+        ...git.map(use => (0, cloudGrantTools_1.gitPushUse)((0, cloudGrantTools_1.toolArgv)(use.text, dialect, ['git']), vars, tools?.cwd)).filter((use) => Boolean(use)),
+        ...(aws.length ? (0, cloudGrantTools_1.awsUses)(aws.map(use => use.text), command, dialect, vars, tools?.aws || (0, cloudGrantTools_1.awsDefaultsFrom)((0, callerEnv_1.callerEnv)())) : []),
+        ...(kube.length ? (0, cloudGrantTools_1.kubeUses)(kube.map(use => ({ tool: use.name, text: use.text })), command, dialect, vars, tools?.kube || (0, cloudGrantTools_1.kubeDefaultsFrom)((0, callerEnv_1.callerEnv)())) : []),
+    ];
+    // Local and sign-in commands act on no environment: no entry, like gcloud's account-level groups.
+    for (const use of toolUses)
+        if (use.where !== undefined)
+            entries.add(`${use.tool}|${use.how}|${use.where}`);
+    if (!gcloud.length)
+        return [...entries].sort();
+    const read = gcloud.map(use => readUse(use.text, dialect, vars));
+    // The line itself switches project or configuration: nothing read from the defaults holds.
+    const defaultsUnreliable = read.some(use => use.mutatesConfig) || /\bcloudsdk_/i.test(command);
+    for (const use of read) {
+        // Account-level and local-SDK commands touch no project: the program binding (and, for a
+        // credential rule, the credential binding) already says everything a grant needs.
+        if (use.where === 'account')
+            continue;
+        let where = use.where;
+        if (where === undefined) {
+            if (use.configuration === null || defaultsUnreliable)
+                where = '?';
+            else {
+                const project = defaultProject(use.configuration);
+                where = project && PROJECT_ID_RE.test(project.toLowerCase()) ? `project=${project.toLowerCase()}` : '?';
+            }
+        }
+        entries.add(`gcloud|${use.how}|${where}`);
+    }
+    return [...entries].sort();
+}
+/** Why a line with these entries cannot carry an Always allow; undefined when it can. */
+function cloudGrantRefusal(entries) {
+    if (!entries || !entries.length)
+        return undefined;
+    const parts = entries.map(entry => entry.split('|'));
+    if (parts.some(p => p[1] === 'delete'))
+        return 'delete';
+    if (parts.some(p => p[1] === 'permissions'))
+        return 'permissions';
+    if (parts.some(p => p[1] === 'protected'))
+        return 'protected';
+    if (parts.some(p => p[1] === '?'))
+        return 'environment_unread';
+    if (parts.some(p => targetUnknown(p[2])))
+        return 'target_unknown';
+    return undefined;
+}
+/** `?`, or any `key=?` part of a compound where (`profile=dev,region=?`). */
+function targetUnknown(where) {
+    return !where || where.split(',').some(part => part === '?' || part.endsWith('=?'));
+}
+/** The tools of the entries that match, sorted, as one phrase: `aws, kubectl`. */
+function toolsWhere(entries, pick) {
+    return [...new Set(entries.map(entry => entry.split('|')).filter(pick).map(p => p[0]))].sort().join(', ');
+}
+/** Every live entry must be in the grant. A grant recorded before entries existed covers no cloud line. */
+function cloudGrantCovers(granted, live) {
+    if (!live || !live.length)
+        return true;
+    return Array.isArray(granted) && live.every(entry => granted.includes(entry));
+}
+/** One short line for the dialog when Always allow is not offered. */
+function describeCloudRefusal(refusal, entries = []) {
+    // Without entries the wording is gcloud's, as before other tools had entries.
+    if (refusal === 'delete')
+        return `Always allow is not offered for ${toolsWhere(entries, p => p[1] === 'delete') || 'gcloud'} deletes.`;
+    if (refusal === 'permissions')
+        return `Always allow is not offered for ${toolsWhere(entries, p => p[1] === 'permissions') || 'gcloud'} permission changes.`;
+    if (refusal === 'protected')
+        return 'Always allow is not offered for a force push, a tag push (--tags, --follow-tags, --all) or a push to main, master, release* or prod*.';
+    if (refusal === 'environment_unread') {
+        const labels = toolsWhere(entries, p => p[1] === '?');
+        const nouns = new Set(labels.split(', ').map(grantTargets_1.unreadNoun));
+        return `Always allow is not offered for ${labels} until the ${nouns.size === 1 ? [...nouns][0] : 'target'} can be read.`;
+    }
+    const tool = toolsWhere(entries, p => targetUnknown(p[2])).split(', ')[0];
+    return TARGET_HINT[tool] || TARGET_HINT.gcloud;
+}
+/** `profile=dev,region=eu-west-1` -> `profile dev, region eu-west-1`. */
+function whereWords(tool, where) {
+    if (where === '?' || !where)
+        return tool === 'gcloud' ? 'unknown project' : 'unknown environment';
+    const parts = where.split(',');
+    const fromDefault = parts.includes('profile-from=default');
+    const words = parts.filter(part => part !== 'profile-from=default').map(part => {
+        const at = part.indexOf('=');
+        const key = part.slice(0, at);
+        const value = part.slice(at + 1);
+        if (value === '?')
+            return `unknown ${key}`;
+        if (value === '-')
+            return `no ${key === 'group' ? 'resource group' : key}`;
+        if (key === 'namespace' && value === '*')
+            return 'all namespaces';
+        return `${key} ${key === 'bucket' ? value.split('+').join(' + ') : value}`;
+    }).join(', ');
+    return fromDefault ? `${words} (profile from the default config — add --profile to bind it)` : words;
+}
+/** How / Where in plain words, for the dialog and the grant list. */
+function describeCloudEntries(entries) {
+    const hows = new Set();
+    const wheres = new Set();
+    for (const entry of entries) {
+        const [tool, how = '', where = ''] = entry.split('|');
+        hows.add(how === '?' ? 'unknown' : how.startsWith('cmd:') ? how.slice(4) : how);
+        wheres.add(whereWords(tool, where));
+    }
+    const list = [...wheres];
+    return { how: [...hows].join(', '), where: list.join(list.some(w => w.includes(', ')) ? '; ' : ', ') };
+}
+/**
+ * The environment names in cloud entries — gcloud projects, aws profiles,
+ * kube contexts — for the dialog's by-name environment tag. The tag itself is
+ * the dialog's one helper; this only says which names it applies to.
+ */
+function cloudEntryEnvironmentNames(entries) {
+    const names = new Set();
+    for (const entry of entries) {
+        for (const part of (entry.split('|')[2] || '').split(',')) {
+            const [key, value] = [part.slice(0, part.indexOf('=')), part.slice(part.indexOf('=') + 1)];
+            if ((key === 'project' || key === 'profile' || key === 'context') && value && value !== '?')
+                names.add(value);
+        }
+    }
+    return [...names];
+}
+/**
+ * The project gcloud uses when the command names none: CLOUDSDK_CORE_PROJECT,
+ * else `[core] project` of the active configuration (`CLOUDSDK_ACTIVE_CONFIG_NAME`,
+ * else the `active_config` file, else `default`) under CLOUDSDK_CONFIG or the
+ * per-user gcloud directory. Any read error or odd value = null (unknown).
+ */
+function activeGcloudProject(configuration, env = (0, callerEnv_1.callerEnv)()) {
+    try {
+        const fromEnv = (env.CLOUDSDK_CORE_PROJECT || '').trim();
+        if (fromEnv)
+            return fromEnv;
+        const home = os.homedir();
+        const dir = (env.CLOUDSDK_CONFIG || '').trim()
+            || (process.platform === 'win32' ? path.join((env.APPDATA || '').trim() || path.join(home, 'AppData', 'Roaming'), 'gcloud') : path.join(home, '.config', 'gcloud'));
+        let name = (configuration || (env.CLOUDSDK_ACTIVE_CONFIG_NAME || '')).trim();
+        if (!name) {
+            const activeFile = path.join(dir, 'active_config');
+            name = fs.existsSync(activeFile) ? fs.readFileSync(activeFile, 'utf8').trim() : 'default';
+        }
+        if (!CONFIG_NAME_RE.test(name))
+            return null;
+        const ini = fs.readFileSync(path.join(dir, 'configurations', `config_${name}`), 'utf8');
+        let section = '';
+        for (const raw of ini.split(/\r?\n/)) {
+            const row = raw.trim();
+            const header = row.match(/^\[([^\]]+)\]$/);
+            if (header) {
+                section = header[1].trim().toLowerCase();
+                continue;
+            }
+            const kv = row.match(/^project\s*=\s*(.*)$/i);
+            if (section === 'core' && kv)
+                return kv[1].trim() || null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cloudGrantTools.d.ts

@@ -0,0 +1,97 @@
+import { type LineVars } from './credentialGrant';
+import type { ShellDialect } from './shellQuoteMask';
+export interface ToolUse {
+    tool: string;
+    how: string;
+    /** Undefined when the use acts on no environment (local / account-level): no entry. */
+    where?: string;
+    /** The use rewrites the tool's own defaults (`aws configure set`, `kubectl config use-context`). */
+    mutatesDefaults: boolean;
+}
+/**
+ * The words after the program on one use's text; empty when the program is not found.
+ * Redirections are the shell's, not arguments to the program: `git push origin x 2>&1`
+ * pushes the same branch as `git push origin x`.
+ */
+export declare function toolArgv(text: string, dialect: ShellDialect, names: readonly string[]): string[];
+/** The profile / region aws uses when the command names none. `null` = unknown. */
+export interface AwsDefaults {
+    profile(): string | null;
+    region(profile: string): string | null;
+}
+/**
+ * `AWS_PROFILE` (else `AWS_DEFAULT_PROFILE`), else `default` when that profile
+ * exists in `~/.aws/config` or `~/.aws/credentials`. Static keys in the
+ * environment (`AWS_ACCESS_KEY_ID`) beat any profile: unknown. Region:
+ * `AWS_REGION`, else `AWS_DEFAULT_REGION`, else the profile's `region` in the
+ * config file (`AWS_CONFIG_FILE` or `~/.aws/config`).
+ */
+export declare function awsDefaultsFrom(env: NodeJS.ProcessEnv): AwsDefaults;
+/** aws uses on the line. `awsLineUnreliable`: the line itself names an AWS_* setting. */
+export declare function awsUses(texts: readonly string[], command: string, dialect: ShellDialect, vars: LineVars, defaults: AwsDefaults): ToolUse[];
+/** The subscription / resource group az falls back to. `null` = unknown. */
+export interface AzDefaults {
+    /** The default subscription id (`isDefault` in azureProfile.json). */
+    subscription(): string | null;
+    /** A subscription name or id -> its id, from azureProfile.json. */
+    subscriptionId(nameOrId: string): string | null;
+    /** `AZURE_DEFAULTS_GROUP`, else `[defaults] group` in the az config file. */
+    group(): string | null;
+}
+/** azureProfile.json / config under AZURE_CONFIG_DIR or `~/.azure`. */
+export declare function azDefaultsFrom(env: NodeJS.ProcessEnv): AzDefaults;
+/** az uses on the line; a line that sets az defaults (`az account set`, `az config set`, `AZURE_*=`) makes every default unknown. */
+export declare function azUses(texts: readonly string[], command: string, dialect: ShellDialect, vars: LineVars, defaults: AzDefaults): ToolUse[];
+/** The workspace a terraform use falls back to. `null` = unknown. */
+export interface TfDefaults {
+    /** `TF_WORKSPACE`, else `<dir>/.terraform/environment`, else `default` — when `cwd` is known. */
+    workspace(dir: string, cwd: string | undefined): string | null;
+}
+export declare function tfDefaultsFrom(env: NodeJS.ProcessEnv): TfDefaults;
+/** terraform / tofu / terragrunt uses; `workspace select` or a `TF_*` assignment on the line makes the workspace unknown. */
+export declare function tfUses(uses: ReadonlyArray<{
+    tool: string;
+    text: string;
+}>, command: string, dialect: ShellDialect, vars: LineVars, defaults: TfDefaults, cwd: string | undefined): ToolUse[];
+export declare function isTfTool(name: string): boolean;
+export declare function isRemoteTool(name: string): boolean;
+export declare function remoteUses(uses: ReadonlyArray<{
+    tool: string;
+    text: string;
+}>, dialect: ShellDialect, vars: LineVars): ToolUse[];
+/** The worst class of the statements in one SQL string. */
+export declare function sqlHow(sql: string): string;
+export declare function isSqlTool(name: string): boolean;
+export declare function sqlUses(uses: ReadonlyArray<{
+    tool: string;
+    text: string;
+}>, command: string, dialect: ShellDialect, vars: LineVars, env: NodeJS.ProcessEnv): ToolUse[];
+/** The branch `HEAD` names in the repository at `dir` (walking up to `.git`), or null. */
+export declare function currentGitBranch(dir: string): string | null;
+/**
+ * `git push`: how = change, or `protected` (a force push, `--all` / `--tags` /
+ * `--follow-tags`, a push to main / master / release* / prod*), or delete
+ * (`--delete`, `:branch`, `--mirror`, `--prune`); `--dry-run` = read. Where =
+ * `remote=<name>,branch=<destination>` — the remote and refspecs on the command;
+ * `HEAD` / no refspec is the current branch, read from `.git/HEAD` only when the
+ * working directory is known (`cwd`), else unknown.
+ */
+export declare function gitPushUse(argv: readonly string[], vars: LineVars, cwd: string | undefined): ToolUse | undefined;
+/** The context and its namespace a kube use falls back to. `null` = unknown. */
+export interface KubeDefaults {
+    context(kubeconfig: string | undefined): string | null;
+    namespace(context: string, kubeconfig: string | undefined): string | null;
+    /** helm's own environment (`HELM_KUBECONTEXT`, `HELM_NAMESPACE`); `unknown` when it points helm elsewhere. */
+    helm: {
+        context?: string;
+        namespace?: string;
+        unknown: boolean;
+    };
+}
+/** `--kubeconfig`, else KUBECONFIG (a path list), else `~/.kube/config`. */
+export declare function kubeDefaultsFrom(env: NodeJS.ProcessEnv): KubeDefaults;
+/** kubectl / oc / helm uses on the line, in order. */
+export declare function kubeUses(uses: ReadonlyArray<{
+    tool: string;
+    text: string;
+}>, command: string, dialect: ShellDialect, vars: LineVars, defaults: KubeDefaults): ToolUse[];