agent-shim 0.0.0 → 7.0.0

package/dist/types/cliError.d.ts

@@ -0,0 +1,27 @@
+/** Exit status for every expected failure that is not a usage error: a missing identity, an invalid config file, a refused launch. */
+export declare const EXIT_FAILURE = 1;
+/** Exit status for a usage error: an unknown command or option, a malformed flag value, or required input missing with no terminal to prompt on. */
+export declare const EXIT_USAGE = 2;
+/**
+ * Base class for every error this CLI throws to represent an expected, user-facing failure: bad input, a missing identity/profile/rule, a malformed config file. `reportFatalError` prints this class as `agent-shim: <message>` with no stack trace and exits with `exitCode`; anything that does not extend it is an unexpected bug, reported by message alone unless `AGENT_SHIM_DEBUG` asks for the stack.
+ */
+export declare abstract class CliError extends Error {
+    /** The process exit status this failure maps to. `EXIT_FAILURE` unless a subclass says otherwise. */
+    readonly exitCode: number;
+}
+/** A usage error: the command line itself is wrong or incomplete. Exits `EXIT_USAGE`. */
+export declare class UsageError extends CliError {
+    readonly exitCode: number;
+    constructor(message: string);
+}
+/**
+ * Raised when a command needs input it would prompt for on a terminal, but standard input is not one. Names the option (or argument) that supplies the input non-interactively, so a script's failure says exactly what to add.
+ */
+export declare class MissingInputError extends UsageError {
+    readonly option: string;
+    constructor(option: string, what: string);
+}
+/** Raised when the user cancels an interactive prompt that a command cannot continue without. */
+export declare class PromptCancelledError extends CliError {
+    constructor();
+}

package/dist/types/config/classify.d.ts

@@ -0,0 +1,49 @@
+import { type CategoryClassification, type CategoryClassificationOverlay, type CategoryName } from "./schema";
+import type { LayoutPaths } from "../paths";
+/** Which map a classification pattern came from. A `local` pattern is an answer the user gave to an "unclassified entry" prompt; a `default` pattern is shipped with the tool. */
+type ClassificationSource = "default" | "local";
+/** One compiled classification pattern: which category it assigns, where it came from, and how specific it is. */
+export interface ClassificationPattern {
+    readonly pattern: string;
+    readonly category: CategoryName;
+    readonly source: ClassificationSource;
+    /** True when the pattern contains no glob metacharacter, so it can only ever match one literal name. */
+    readonly isExact: boolean;
+    /** Position of the pattern within its own category list, used only as the final deterministic tie-break. */
+    readonly ordinal: number;
+    readonly matches: (name: string) => boolean;
+}
+/** The outcome of classifying a set of real top-level `~/.claude` entry names. */
+export interface ClassifyResult {
+    /** Every input name mapped to its category, or to null when nothing in either map recognises it. */
+    readonly classification: ReadonlyMap<string, CategoryName | null>;
+    /** The input names that nothing recognised, in input order. These are the names `agent-shim configure` prompts about. */
+    readonly unclassified: readonly string[];
+    /** For each classified name, the pattern that decided it — used by `agent-shim check` to explain a classification. */
+    readonly decidedBy: ReadonlyMap<string, ClassificationPattern>;
+}
+/** True when `pattern` contains no glob metacharacter, so it matches exactly one literal name. */
+export declare function isExactPattern(pattern: string): boolean;
+/** Compiles a shipped classification map plus an optional local overlay into one flat, ranked pattern list. */
+export declare function compileClassificationPatterns(defaults: CategoryClassification, overlay?: CategoryClassificationOverlay): ClassificationPattern[];
+/** The classification input every real call site needs: the shipped defaults plus this user's own local overlay, when one exists. */
+export interface LoadedClassification {
+    readonly defaults: CategoryClassification;
+    readonly overlay?: CategoryClassificationOverlay;
+}
+/**
+ * Loads the classification input `classifyEntries` needs — the shipped `categories.default.json`, plus `categories.local.json` when the user has answered at least one "unclassified entry" prompt.
+ *
+ * Real-wired convenience over reading and validating the two files. Every command that classifies anything (`cli.ts`'s farm runtime, `check`, `configure`, `identity resolve-conflicts`) was independently repeating this exact pair of `readJson`/`.parse()` calls before this existed; centralising it here means the four command files stay thin call sites rather than each holding its own copy of a validation step that never varies between them.
+ */
+export declare function loadClassification(paths: LayoutPaths): LoadedClassification;
+/**
+ * Classifies a list of real top-level `~/.claude` entry names against the shipped category map plus an optional local overlay.
+ *
+ * An unrecognised name maps to `null` rather than being silently assumed safe or silently dropped: the resolver treats it as not-shared and reports it, and `agent-shim configure` prompts for an answer that is then written to the local overlay.
+ */
+export declare function classifyEntries(names: readonly string[], options: {
+    defaults: CategoryClassification;
+    overlay?: CategoryClassificationOverlay;
+}): ClassifyResult;
+export {};

package/dist/types/config/load.d.ts

@@ -0,0 +1,42 @@
+import { type PublicExplorerSync } from "cosmiconfig";
+import type { z } from "zod";
+import { CliError } from "../cliError";
+/**
+ * A configuration file that has been read, parsed, and validated.
+ *
+ * `entryOrder` and `ruleEntryOrders` capture each `entries` object's own key insertion order as an explicit ordinal array, taken from the *raw* parsed value before Zod ever sees it. This is not paranoia about JSON key ordering: `schema.parse()` returns a fresh deep clone, and relying on key order implicitly surviving that clone would make the resolver's same-layer source-order tie-break depend on an implementation detail of a third-party library. Capturing it explicitly at load time makes it data.
+ */
+export interface LoadedFile<T> {
+    readonly filepath: string;
+    readonly config: T;
+    /** Key insertion order of the file's own top-level `entries` object; empty when the file has none. */
+    readonly entryOrder: readonly string[];
+    /** For a directory-rules file: the key insertion order of each rule's `entries` object, indexed the same as `rules[]`. Empty for every other file shape. */
+    readonly ruleEntryOrders: readonly (readonly string[])[];
+}
+/**
+ * Builds the cosmiconfig explorer used for every read.
+ *
+ * Only `load(filepath)` is ever called on it — never `search()`. `search()` stops at the first config file found while walking upward, and this design needs the exact opposite: every ancestor collected, shallowest-first. `src/resolve/walk.ts` does its own directory walk and this module loads each level it visits, so cosmiconfig contributes its format flexibility (JSON, YAML, JS) without its traversal semantics.
+ */
+export declare function createExplorer(moduleName?: string): PublicExplorerSync;
+/** Reads the key insertion order of `value.entries`, when `value` is an object carrying an `entries` object. */
+export declare function captureEntryOrder(value: unknown): readonly string[];
+/** Reads the per-rule key insertion order of a directory-rules file's `rules[].entries` objects. */
+export declare function captureRuleEntryOrders(value: unknown): readonly (readonly string[])[];
+/** Raised when a config file exists but fails Zod validation, so the caller can report the offending path alongside the issue list. */
+export declare class ConfigValidationError extends CliError {
+    readonly filepath: string;
+    readonly issues: readonly z.core.$ZodIssue[];
+    constructor(filepath: string, issues: readonly z.core.$ZodIssue[]);
+}
+/** Injected reader for a single config file, so tests never touch a real filesystem. Returns undefined when the file does not exist. */
+export type ConfigFileReader = (filepath: string) => unknown;
+/** A cosmiconfig-backed reader: loads and parses one file by path, returning undefined when it is missing or empty. */
+export declare function cosmiconfigReader(explorer?: Readonly<PublicExplorerSync>): ConfigFileReader;
+/**
+ * Loads one config file by exact path, validates it against `schema`, and captures its entries key order.
+ *
+ * Returns undefined when the file does not exist or is empty. Throws ConfigValidationError when it exists but does not validate — a malformed config is never silently ignored or half-applied.
+ */
+export declare function loadConfigFile<S extends z.ZodType>(filepath: string, schema: S, read?: ConfigFileReader): LoadedFile<z.infer<S>> | undefined;