@guilz-dev/belay 0.9.2 → 0.9.4

package/dist/core/effect-ir/shell-lower/requirement.js

@@ -0,0 +1,65 @@
+export const SECRET_PATH_PATTERN = /(?:^|[/\\])(?:\.env(?:\..*)?|credentials?|secrets?|id_rsa)(?:$|[/\\])/i;
+export const CONTROL_PLANE_PATH_PATTERN = /^(?:\/etc(?:\/|$)|\/var\/run(?:\/|$)|.*(?:^|[/\\])\.(?:git|ssh|cursor|claude)(?:[/\\]|$))/;
+export function requirement(tag, action, resource, segment, signals) {
+    return {
+        tag,
+        action,
+        resource,
+        evidence: {
+            level: tag === 'indeterminate' ? 'indeterminate' : 'certain',
+            signals: [...new Set(signals)].sort(),
+            basis: ['shell_semantic_lowering'],
+        },
+        provenance: { segment },
+    };
+}
+export function processRequirement(command, operation, segment, signals) {
+    return requirement('process.exec', 'process.exec', { kind: 'executable', command, operation }, segment, signals);
+}
+export function unsupportedProcess(command, segment, signal) {
+    return [
+        processRequirement(command, 'spawn', segment, [signal]),
+        requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, segment, [signal]),
+    ];
+}
+export function addWriteEffects(requirements, resolved, segment, signals) {
+    requirements.push(requirement('fs.write', 'fs.write', { kind: 'path', path: resolved }, segment, signals));
+    if (CONTROL_PLANE_PATH_PATTERN.test(resolved)) {
+        requirements.push(requirement('control_plane.write', 'control_plane.write', { kind: 'path', path: resolved }, segment, [...signals, 'protected_path']));
+    }
+}
+export function addSecretRead(requirements, resolved, segment) {
+    if (SECRET_PATH_PATTERN.test(resolved)) {
+        requirements.push(requirement('secret.read', 'secret.read', { kind: 'path', path: resolved }, segment, [
+            'secret_path_read',
+        ]));
+    }
+}
+export function ensureRequirement(requirements, candidate) {
+    if (!requirements.some((entry) => entry.action === candidate.action &&
+        JSON.stringify(entry.resource) === JSON.stringify(candidate.resource))) {
+        requirements.push(candidate);
+    }
+}
+export function withProvenances(requirementValue, provenance, contributing) {
+    const provenances = [
+        ...(requirementValue.provenances ?? [requirementValue.provenance]),
+        contributing,
+        provenance,
+    ].filter((candidate, index, all) => all.findIndex((entry) => JSON.stringify(entry) === JSON.stringify(candidate)) === index);
+    return { ...requirementValue, provenance, provenances };
+}
+export function withInnerProvenance(requirementValue, innerCommand, launcher, outerSegment) {
+    const provenance = {
+        ...requirementValue.provenance,
+        segment: outerSegment,
+        innerCommand: requirementValue.provenance.innerCommand ?? innerCommand,
+        ...(launcher === 'npm' || launcher === 'pnpm' ? { launcher, phase: 'delegate' } : {}),
+    };
+    const launcherProvenance = {
+        segment: outerSegment,
+        innerCommand,
+        ...(launcher === 'npm' || launcher === 'pnpm' ? { launcher, phase: 'delegate' } : {}),
+    };
+    return withProvenances(requirementValue, provenance, launcherProvenance);
+}

package/dist/core/effect-ir/shell-lower/segment.d.ts

@@ -0,0 +1,11 @@
+import type { ShellEffectRequirement, ShellEffectSegment } from '../shell-build.js';
+import type { EffectPlan } from '../types.js';
+export declare function requiresKnownCwd(requirementValue: ShellEffectRequirement): boolean;
+export declare function joinNestedOpacity(outer: EffectPlan['opacity'], nested: ShellEffectSegment): EffectPlan['opacity'];
+export declare function startsLocalPostgresService(command: string): boolean;
+export declare function resolveCdTransition(command: string, currentCwd: string): {
+    cwd: string;
+    known: boolean;
+} | null;
+export declare function shellSegment(commandRedacted: string, segmentHead: string, requirements: ShellEffectRequirement[], opacity: EffectPlan['opacity'], signals: Set<string>): ShellEffectSegment;
+export declare function dynamicResourceSignal(resource: ShellEffectRequirement['resource']): string | null;

package/dist/core/effect-ir/shell-lower/segment.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { tokenizeShell } from '../../shell-tokenizer.js';
+import { joinEffectOpacity } from '../normalize.js';
+import { requirement } from './requirement.js';
+import { resolvePathOperand } from './tokens.js';
+const DYNAMIC_SHELL_VALUE_PATTERN = /(?:\$\(|`|\$(?:\d+|[@*#?$!-]|\{[^}]*\}|[A-Za-z_][A-Za-z0-9_]*))/;
+const SHELL_GLOB_PATTERN = /[*?[]/;
+export function requiresKnownCwd(requirementValue) {
+    if (requirementValue.action === 'fs.write' ||
+        requirementValue.action === 'git.ref.write' ||
+        requirementValue.action === 'control_plane.write') {
+        return true;
+    }
+    return (requirementValue.action === 'process.exec' &&
+        requirementValue.resource.kind === 'executable' &&
+        requirementValue.resource.operation === 'spawn');
+}
+export function joinNestedOpacity(outer, nested) {
+    const nestedOpacity = nested.completeness === 'partial' && nested.opacity === 'transparent'
+        ? 'recursive'
+        : nested.opacity;
+    return joinEffectOpacity(outer, nestedOpacity);
+}
+export function startsLocalPostgresService(command) {
+    const tokens = tokenizeShell(command);
+    return (path.basename(tokens[0] ?? '') === 'docker' &&
+        tokens[1] === 'compose' &&
+        ['up', 'start', 'restart'].includes(tokens[2] ?? '') &&
+        tokens.includes('postgres'));
+}
+export function resolveCdTransition(command, currentCwd) {
+    const tokens = tokenizeShell(command);
+    if (path.basename(tokens[0] ?? '') !== 'cd') {
+        return null;
+    }
+    const target = tokens[1] ?? '~';
+    if (!target || target === '-' || target.includes('$') || target.includes('`')) {
+        return { cwd: currentCwd, known: false };
+    }
+    return { cwd: resolvePathOperand(target, currentCwd), known: true };
+}
+export function shellSegment(commandRedacted, segmentHead, requirements, opacity, signals) {
+    const normalizedRequirements = requirements.flatMap((entry) => {
+        const dynamicSignal = dynamicResourceSignal(entry.resource);
+        if (dynamicSignal) {
+            return [
+                { ...entry, resource: { kind: 'unknown' } },
+                requirement('indeterminate', 'indeterminate', { kind: 'unknown' }, entry.provenance.segment ?? commandRedacted, [...entry.evidence.signals, dynamicSignal]),
+            ];
+        }
+        return [entry];
+    });
+    const partial = normalizedRequirements.some((entry) => entry.tag === 'indeterminate' || entry.action === 'indeterminate');
+    return {
+        commandRedacted,
+        segmentHead,
+        requirements: normalizedRequirements,
+        completeness: partial ? 'partial' : 'complete',
+        opacity,
+        signals: [...signals].sort(),
+    };
+}
+export function dynamicResourceSignal(resource) {
+    const expanded = (value) => Boolean(value && DYNAMIC_SHELL_VALUE_PATTERN.test(value));
+    const pathLike = (value, allowSemanticWildcard = false) => Boolean(value && (expanded(value) || (!allowSemanticWildcard && SHELL_GLOB_PATTERN.test(value))));
+    switch (resource.kind) {
+        case 'path':
+            return pathLike(resource.path) ? 'shell.path_unresolved' : null;
+        case 'network':
+            return expanded(resource.host) || expanded(resource.protocol)
+                ? 'shell.network_resource_unresolved'
+                : null;
+        case 'git-ref':
+            return pathLike(resource.repoPath) || pathLike(resource.ref, resource.ref.endsWith('/*'))
+                ? 'shell.git_resource_unresolved'
+                : null;
+        case 'executable':
+            return expanded(resource.command) ? 'shell.executable_unresolved' : null;
+        default:
+            return null;
+    }
+}

package/dist/core/effect-ir/shell-lower/tokens.d.ts

@@ -0,0 +1,26 @@
+import { type ShellToken } from '../../shell-tokenizer.js';
+export declare const ENV_PREFIX_PATTERN: RegExp;
+export declare const LOOPBACK_HOSTS: Set<string>;
+export declare const METADATA_ONLY_FLAGS: Set<string>;
+export interface EnvironmentExtraction {
+    env: Readonly<Record<string, string | undefined>>;
+    commandTokens?: string[];
+    malformed: boolean;
+    changedNames: ReadonlySet<string>;
+}
+export declare function extractEnvironment(tokens: string[], inherited: Readonly<Record<string, string | undefined>> | undefined): EnvironmentExtraction;
+export declare function expandKnownVariables(token: string, env: Readonly<Record<string, string | undefined>>): string;
+export declare function stripRedirects(tokens: string[]): string[];
+export declare function stripStructuredRedirects(tokens: readonly ShellToken[]): ShellToken[];
+export declare function alignStructuredTokens(tokens: readonly ShellToken[], values: readonly string[]): ShellToken[];
+export declare function resolvePathOperand(operand: string, cwd: string): string;
+export declare function isOptionToken(value: string): boolean;
+export declare function isShellHead(head: string): boolean;
+export declare function pipeToShell(command: string): boolean;
+export declare function executableBaseName(head: string): string;
+export declare function isMetadataOnlyArgv(argv: string[]): boolean;
+export declare function databaseEndpoint(raw: string | undefined): {
+    host: string;
+    protocol: string;
+    port?: number;
+} | null;

package/dist/core/effect-ir/shell-lower/tokens.js

@@ -0,0 +1,183 @@
+import path from 'node:path';
+import { isFdDuplication, isRedirectOperator } from '../../shell-tokenizer.js';
+export const ENV_PREFIX_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '0:0:0:0:0:0:0:1']);
+export const METADATA_ONLY_FLAGS = new Set(['--version', '-v', '-V', '--help', '-h']);
+export function extractEnvironment(tokens, inherited) {
+    const env = { ...inherited };
+    const changedNames = new Set();
+    if (tokens[0] === 'env') {
+        let index = 1;
+        let malformed = false;
+        while (index < tokens.length) {
+            const option = tokens[index] ?? '';
+            if (option === '-u' || option === '--unset') {
+                const name = tokens[index + 1] ?? '';
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+                    malformed = true;
+                    index += 1;
+                    break;
+                }
+                delete env[name];
+                changedNames.add(name);
+                index += 2;
+                continue;
+            }
+            if (option.startsWith('--unset=')) {
+                const name = option.slice('--unset='.length);
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+                    malformed = true;
+                    index += 1;
+                    break;
+                }
+                delete env[name];
+                changedNames.add(name);
+                index += 1;
+                continue;
+            }
+            if (option === '-i' || option === '--ignore-environment') {
+                for (const name of Object.keys(env)) {
+                    delete env[name];
+                }
+                changedNames.add('*');
+                index += 1;
+                continue;
+            }
+            if (option === '--') {
+                index += 1;
+                break;
+            }
+            if (option.startsWith('-')) {
+                malformed = true;
+                index += 1;
+                break;
+            }
+            break;
+        }
+        while (index < tokens.length) {
+            const token = tokens[index] ?? '';
+            const match = ENV_PREFIX_PATTERN.exec(token);
+            if (!match) {
+                break;
+            }
+            const [, name, value] = match;
+            if (name) {
+                env[name] = expandKnownVariables(value ?? '', env);
+                changedNames.add(name);
+            }
+            index += 1;
+        }
+        const commandTokens = tokens.slice(index);
+        return {
+            env,
+            commandTokens,
+            malformed: malformed || commandTokens.length === 0,
+            changedNames,
+        };
+    }
+    for (const token of tokens) {
+        const match = ENV_PREFIX_PATTERN.exec(token);
+        if (!match) {
+            break;
+        }
+        const [, name, value] = match;
+        if (name) {
+            env[name] = expandKnownVariables(value ?? '', env);
+            changedNames.add(name);
+        }
+    }
+    return { env, malformed: false, changedNames };
+}
+export function expandKnownVariables(token, env) {
+    return token.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (raw, a, b) => {
+        const value = env[a ?? b];
+        return value === undefined ? raw : value;
+    });
+}
+export function stripRedirects(tokens) {
+    const stripped = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index] ?? '';
+        if (isFdDuplication(token)) {
+            continue;
+        }
+        if (!isRedirectOperator(token)) {
+            stripped.push(token);
+            continue;
+        }
+        index += 1;
+    }
+    return stripped;
+}
+export function stripStructuredRedirects(tokens) {
+    const stripped = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token)
+            continue;
+        if (isFdDuplication(token.value)) {
+            continue;
+        }
+        if (!isRedirectOperator(token.value)) {
+            stripped.push(token);
+            continue;
+        }
+        index += 1;
+    }
+    return stripped;
+}
+export function alignStructuredTokens(tokens, values) {
+    if (values.length === 0)
+        return [];
+    for (let start = tokens.length - values.length; start >= 0; start -= 1) {
+        const candidate = tokens.slice(start);
+        if (candidate.length === values.length &&
+            candidate.every((token, index) => token.value === values[index])) {
+            return candidate;
+        }
+    }
+    return [];
+}
+export function resolvePathOperand(operand, cwd) {
+    if (operand === '~') {
+        return process.env.HOME ?? operand;
+    }
+    if (operand.startsWith('~/')) {
+        return path.join(process.env.HOME ?? '~', operand.slice(2));
+    }
+    return path.resolve(cwd, operand);
+}
+export function isOptionToken(value) {
+    return value.startsWith('-') || value.startsWith('+');
+}
+export function isShellHead(head) {
+    return head === 'bash' || head === 'sh' || head === 'zsh' || head === 'dash' || head === 'fish';
+}
+export function pipeToShell(command) {
+    return /(?:^|[|;&]\s*)(?:bash|sh|zsh|dash|fish)(?:\s|$)/.test(command) && /\|/.test(command);
+}
+export function executableBaseName(head) {
+    return path.basename(head);
+}
+export function isMetadataOnlyArgv(argv) {
+    return argv.length > 0 && argv.every((token) => METADATA_ONLY_FLAGS.has(token));
+}
+export function databaseEndpoint(raw) {
+    if (!raw || raw.includes('$')) {
+        return null;
+    }
+    try {
+        const url = new URL(raw);
+        if (!url.hostname || !url.protocol) {
+            return null;
+        }
+        return {
+            host: url.hostname.toLowerCase(),
+            protocol: url.protocol.slice(0, -1),
+            ...(url.port ? { port: Number(url.port) } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/effect-ir/shell-lower.d.ts

@@ -1,11 +1,6 @@
+import type { LowerShellEffectPlanParams } from './shell-lower/context.js';
 import type { EffectPlan } from './types.js';
-export interface LowerShellEffectPlanParams {
-    command: string;
-    cwd: string;
-    repoRoot: string;
-    inputFingerprint: string;
-    env?: Readonly<Record<string, string | undefined>>;
-}
+export type { LowerShellEffectPlanParams } from './shell-lower/context.js';
 /**
  * Parse and lower a general shell command into the canonical Task 2 model.
  * This function only produces effects; it does not evaluate policy or return a