@agentwhy/cli 0.0.0-dev

package/dist/ports/multi-chooser.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/notifier.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/onboarding-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/printer.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/text-input.js

@@ -0,0 +1 @@
+export {};

package/dist/refuse/command-reach.js

@@ -0,0 +1,135 @@
+import { resolve } from 'node:path';
+import { hasGlob, matchesName, reachOf } from '../core/access/search-reach.js';
+import { protectionOf } from '../core/policy/policy.js';
+import { FileAccessError } from '../ports/file-access-error.js';
+/**
+ * How many directory entries one command may cost before the walk gives up. A search is walked breadth first, so a
+ * protected file near where it starts - a `.env` at the root - is met in the first listing; this bounds only a search
+ * that reaches nothing protected through a very large tree, which a hook on every shell command must not stall on.
+ */
+const MAX_ENTRIES = 50_000;
+/**
+ * The first protected file a command line would open without naming it: through a word the shell expands (`cat .env*`),
+ * or through a recursive search (`grep -rn KEY .`) whose own filters do not leave it out (R21a). Undefined when it
+ * reaches none. Paths are shown as the command would print them, relative to where it starts.
+ */
+export async function protectedFileReached(command, policy, place, directories) {
+    const { searches, globs } = reachOf(command);
+    for (const word of globs) {
+        for (const path of await expand(word, place, directories)) {
+            const pattern = protectingPattern(policy, path, place);
+            if (pattern !== undefined)
+                return { kind: 'glob', word, path, pattern };
+        }
+    }
+    const budget = { left: MAX_ENTRIES };
+    for (const search of searches) {
+        const found = await walk(search, policy, place, directories, budget);
+        if (found !== undefined)
+            return { kind: 'search', ...found };
+    }
+    return budget.left < 0 ? { kind: 'too-large' } : undefined;
+}
+/**
+ * The names a shell would put in place of a glob, as it would write them. Only a glob in the last part of the word is
+ * expanded; a wildcard in a directory part is left alone, which misses a rarer command rather than guessing at one.
+ */
+async function expand(word, place, directories) {
+    const slash = word.lastIndexOf('/');
+    const directory = word.slice(0, slash + 1);
+    const name = word.slice(slash + 1);
+    if (hasGlob(directory) || !hasGlob(name))
+        return [];
+    const entries = await listOf(directories, located(directory === '' ? '.' : directory, place));
+    return entries.filter((entry) => matchesName(entry.name, name, { period: true })).map((entry) => `${directory}${entry.name}`);
+}
+async function walk(search, policy, place, directories, budget) {
+    const roots = (await Promise.all(search.roots.map(async (root) => (hasGlob(root) ? expand(root, place, directories) : [root])))).flat();
+    const queue = [];
+    for (const root of roots) {
+        const kind = await kindOf(directories, located(root, place));
+        // A file named on the command line is read whatever the filters say about names met on the way down.
+        if (kind === 'file') {
+            const pattern = protectingPattern(policy, root, place);
+            if (pattern !== undefined)
+                return { path: root, pattern };
+        }
+        else if (kind === 'directory') {
+            queue.push(root);
+        }
+    }
+    for (let directory = queue.shift(); directory !== undefined; directory = queue.shift()) {
+        const entries = await listOf(directories, located(directory, place));
+        budget.left -= entries.length;
+        if (budget.left < 0)
+            return undefined;
+        const below = [];
+        for (const entry of entries) {
+            if (!search.hidden && entry.name.startsWith('.'))
+                continue;
+            const path = joined(directory, entry.name);
+            if (entry.kind === 'directory') {
+                if (!matchesAny(entry.name, search.excludeDirs))
+                    below.push(path);
+            }
+            else if (entry.kind === 'file' && isSearched(entry.name, search)) {
+                const pattern = protectingPattern(policy, path, place);
+                if (pattern !== undefined)
+                    return { path, pattern };
+            }
+        }
+        queue.push(...below);
+    }
+    return undefined;
+}
+function isSearched(name, search) {
+    return (search.includes.length === 0 || matchesAny(name, search.includes)) && !matchesAny(name, search.excludes);
+}
+/** A program matching its own globs has no rule about a leading dot. */
+function matchesAny(name, globs) {
+    return globs.some(({ glob, caseless }) => matchesName(name, glob, { period: false, caseless: caseless === true }));
+}
+/** A path as a search prints it: `.env` below `.`, `apps/web/.env` below `apps`. */
+function joined(directory, name) {
+    if (directory === '.' || directory === './')
+        return name;
+    return directory.endsWith('/') ? `${directory}${name}` : `${directory}/${name}`;
+}
+/** Tried as written first, as a report reads a command; then absolute, for a rule written with the whole path. */
+function protectingPattern(policy, path, place) {
+    return (protectionOf(policy, path) ?? protectionOf(policy, located(path, place)))?.pattern;
+}
+/**
+ * The absolute path a word names once the shell has rewritten it: `~`, `$HOME` and `${HOME}` at its start become the
+ * home directory, `$PWD` and `${PWD}` where the command runs. Read as written, `grep -rn KEY ~/app` named a directory
+ * that is not there, and the `.env` below the real one was let through. Quoting was removed before the word got here, so
+ * a quoted `'~/app'`, which the shell leaves as it is, is read as the home too: a refusal the agent can answer, never a
+ * file let through. Any other variable is not known here and is left as written.
+ */
+function located(word, place) {
+    const expanded = word
+        .replace(/^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/, () => place.home)
+        .replace(/^(?:\$PWD|\$\{PWD\})(?=\/|$)/, () => place.workingDirectory);
+    return resolve(place.workingDirectory, expanded);
+}
+/** What cannot be listed is not searched by the command either, so it reaches nothing here. */
+async function listOf(directories, path) {
+    try {
+        return await directories.list(path);
+    }
+    catch (error) {
+        if (!(error instanceof FileAccessError))
+            throw error;
+        return [];
+    }
+}
+async function kindOf(directories, path) {
+    try {
+        return await directories.kindOf(path);
+    }
+    catch (error) {
+        if (!(error instanceof FileAccessError))
+            throw error;
+        return undefined;
+    }
+}

package/dist/refuse/command-refusal.js

@@ -0,0 +1,88 @@
+import { isAbsolute, join, dirname } from 'node:path';
+import { parsePreToolUseInput } from '../adapter/claude-code/hooks/pre-tool-use-input.js';
+import { PROJECT_HOOKS } from '../adapter/codex/contract/hooks.js';
+import { parseCodexPreToolUseInput } from '../adapter/codex/hooks/pre-tool-use-input.js';
+import { protectedPathsInCommand } from '../core/access/protected-access.js';
+import { FileAccessError } from '../ports/file-access-error.js';
+import { choosePolicy } from '../report/choose-policy.js';
+import { blockingOnly } from '../core/policy/policy.js';
+import { protectedFileReached } from './command-reach.js';
+/** How many folders above the session's the project is looked for in: deeper than any project, short of a loop. */
+const MAX_PROJECT_DEPTH = 64;
+/** A command line is a few kilobytes; past this the input is not held at all, and the command is not checked. */
+const MAX_INPUT_BYTES = 1024 * 1024;
+/**
+ * `agentwhy refuse`: the project's own rules, applied to a shell command line before it runs
+ * (`specs/2026-09-16-worth-running-every-day.md` R18-R21a). It adds no rule of its own - the policy is chosen as `report`
+ * chooses it - and it reads the line with the code a report uses. A command that names a protected path is refused;
+ * so is one that would open a protected file without naming it, through a glob or a recursive search. The usage says
+ * what still walks past it.
+ */
+export class CommandRefusal {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async decide(options) {
+        const { codex = false, ...choice } = options;
+        const text = await this.#dependencies.input.readAll(MAX_INPUT_BYTES);
+        const parsed = text === undefined ? undefined : codex ? parseCodexPreToolUseInput(text) : parsePreToolUseInput(text);
+        if (parsed === undefined || 'unusable' in parsed)
+            return { kind: 'not-checked', reason: 'input' };
+        if ('anotherTool' in parsed)
+            return { kind: 'allow' };
+        const settled = codex ? await this.#inCodexProject(choice, parsed.cwd ?? this.#dependencies.workingDirectory) : choice;
+        if (settled === undefined)
+            return { kind: 'not-checked', reason: 'project' };
+        const chosen = await choosePolicy(settled, this.#dependencies.files, this.#dependencies.tell);
+        if ('errors' in chosen)
+            return { kind: 'not-checked', reason: 'policy' };
+        // F57: a file a person asked only to be told about is theirs to let the agent read. Only what is blocked is refused.
+        const policy = { policy: blockingOnly(chosen.policy) };
+        const [first, ...others] = protectedPathsInCommand(parsed.command, policy.policy);
+        if (first !== undefined)
+            return { kind: 'refuse', path: first[0], pattern: first[1], others: others.length, route: { kind: 'named' } };
+        const workingDirectory = parsed.cwd ?? this.#dependencies.workingDirectory;
+        // R20 holds for the walk too: whatever it meets on disk, a failure lets the command run and is said to the user,
+        // never an exception from a hook that runs before every shell command.
+        const place = { workingDirectory, home: this.#dependencies.home };
+        const reach = await protectedFileReached(parsed.command, policy.policy, place, this.#dependencies.directories).catch(() => ({ kind: 'too-large' }));
+        if (reach === undefined)
+            return { kind: 'allow' };
+        if (reach.kind === 'too-large')
+            return { kind: 'not-checked', reason: 'search' };
+        const route = reach.kind === 'glob' ? { kind: 'glob', word: reach.word } : { kind: 'search' };
+        return { kind: 'refuse', path: reach.path, pattern: reach.pattern, others: 0, route };
+    }
+    /**
+     * CK3: Codex runs its hook in the session's folder, which can lie below the project, and names the project nowhere
+     * (CKB6). A relative settings path is read in the project: the nearest folder, at or above `folder`, that holds the
+     * `.codex/hooks.json` this hook is written in. None found is `undefined`: the command runs, and is said to be unchecked.
+     */
+    async #inCodexProject(choice, folder) {
+        const relative = choice.settingsPath;
+        if (relative === undefined || isAbsolute(relative))
+            return choice;
+        for (let at = folder, depth = 0; depth < MAX_PROJECT_DEPTH; depth += 1) {
+            if (await this.#holds(join(at, PROJECT_HOOKS.directory, PROJECT_HOOKS.file)))
+                return { ...choice, settingsPath: join(at, relative) };
+            const up = dirname(at);
+            if (up === at)
+                return undefined;
+            at = up;
+        }
+        return undefined;
+    }
+    /** Whether a file is there to read; a folder or anything unreadable is not. */
+    async #holds(path) {
+        try {
+            await this.#dependencies.files.readText(path);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof FileAccessError)
+                return false;
+            throw error;
+        }
+    }
+}

package/dist/refuse/render/codex-stop-words.js

@@ -0,0 +1,21 @@
+/**
+ * A continuation request, so the refusal is said in the conversation by Codex, in the user's language (CK13). Codex's
+ * VS Code chat folds the hook's own words into the turn's collapsed steps, so the reply is the one place a person sees
+ * agentwhy there: it is asked to lead with agentwhy's name. The person reads this request too - the VS Code chat shows
+ * it as "Hook feedback" and the terminal as "Blocked by hook" (CKB14) - so it is three short sentences in the page's
+ * words (guidelines §7): what happened, what to say, and what not to do. It gives no text to copy.
+ */
+export function codexStopInstruction(refusals) {
+    const paths = [...new Set(refusals.map((refusal) => refusal.path))];
+    const named = paths.slice(0, 3).map((path) => JSON.stringify(path));
+    if (paths.length > 3)
+        named.push(`${paths.length - 3} more`);
+    const listed = named.length === 1 ? named[0] : `${named.slice(0, -1).join(', ')} and ${named.at(-1)}`;
+    const one = refusals.length === 1;
+    const [files, them] = paths.length === 1 ? ['file', 'it'] : ['files', 'them'];
+    return [
+        `agentwhy stopped ${one ? 'a command' : 'commands'} that would have read the private ${files} ${listed}, so ${one ? 'it' : 'they'} did not run.`,
+        `Say so to the user in one short message in their language, starting with **agentwhy**, and add that they can open the ${files} in their editor.`,
+        `Don't read ${them} another way or ask for what's in ${them}.`,
+    ].join(' ');
+}

package/dist/refuse/render/refusal-words.js

@@ -0,0 +1,34 @@
+import { HOOK_OUTPUT } from '../../adapter/claude-code/contract/hooks.js';
+const NOT_CHECKED = {
+    arguments: 'agentwhy refuse was given arguments it does not recognise, so this command was not checked.',
+    input: 'agentwhy refuse could not read the hook input, so this command was not checked.',
+    policy: 'agentwhy refuse could not read the policy it was given, so this command was not checked.',
+    search: 'agentwhy refuse could not look through everything this search reaches, so this command was not checked.',
+    project: 'agentwhy refuse found no .codex/hooks.json in this folder or above it, so it could not read the project\'s rules and this command was not checked.',
+};
+/** Said to the user, as a hook's JSON on stdout, when a command ran without being checked (R20). */
+export function notCheckedMessage(reason) {
+    return JSON.stringify({ [HOOK_OUTPUT.systemMessage]: NOT_CHECKED[reason] });
+}
+/**
+ * What the agent is told when a command is refused (R19). A named path is the one the agent just wrote, so naming it
+ * tells the model nothing new. A path reached through a glob or a search is one the agent did not write: its name is
+ * given - a listing of the directory would show it anyway - and never anything from inside it (R21a). No other route
+ * is suggested. The person can inspect the file locally without putting its contents in the conversation.
+ */
+export function refusalReason(path, pattern, others, route) {
+    const more = others === 0 ? '' : `, and ${others} more protected ${others === 1 ? 'path' : 'paths'}`;
+    return (`agentwhy refused this command: ${howItReaches(route, path)}, which this project's policy protects (${pattern})${more}. ` +
+        "Protected files are kept out of the agent's reach. Tell the user agentwhy blocked the command. " +
+        "Do not ask them to paste this file or a secret value into the chat; they can inspect it in their IDE.\n");
+}
+function howItReaches(route, path) {
+    switch (route.kind) {
+        case 'named':
+            return `it names ${path}`;
+        case 'glob':
+            return `${route.word} expands to ${path}`;
+        case 'search':
+            return `this search would read ${path}`;
+    }
+}