@warlock.js/ai-workspace 5.29.0 → 5.31.0

package/esm/policy/shell-check.d.mts

@@ -0,0 +1,64 @@
+import { WorkspacePolicy } from "../contracts/workspace-policy.type.mjs";
+import { WorkspaceShellRefusalReason } from "../errors.mjs";
+
+//#region ../../packages/ai-workspace/src/policy/shell-check.d.ts
+/** How a shell-mode line touches a path the jail has to vet. */
+type WorkspaceShellPathAccess = "read" | "write" | "cwd";
+/** A path a shell-mode line redirects to/from or `cd`s into. */
+interface WorkspaceShellPath {
+  /** Absolute path, resolved lexically against the workspace root (or an earlier `cd`). */
+  path: string;
+  /** What the line does with it. */
+  access: WorkspaceShellPathAccess;
+  /** The target as written in the line. */
+  target: string;
+}
+/**
+ * The shell policy's verdict on one command line — see
+ * {@link checkShellCommand}.
+ */
+interface WorkspaceShellCheck {
+  /** Whether the line may run (path targets still get a symlink-aware recheck in `exec`). */
+  allowed: boolean;
+  /** Why it was refused. */
+  reason?: WorkspaceShellRefusalReason;
+  /** Model-facing refusal text: the cause, and how to fix the command. */
+  message?: string;
+  /** The executable the refusal is about, when there is one. */
+  executable?: string;
+  /** The redirection target or `cd` directory a `"path-escape"` refusal is about. */
+  path?: string;
+  /** The argv of every simple command checked, in order (wrapped commands included). */
+  commands: string[][];
+  /** Shell mode: every redirection target and `cd` directory, for the jail recheck. */
+  paths: WorkspaceShellPath[];
+}
+/**
+ * The shell policy's verdict on a command line, without touching the
+ * filesystem.
+ *
+ * - **argv mode** (`interpreter: "none"`, the default): the line must
+ *   tokenize into one argv; otherwise it is refused with a
+ *   `"metacharacter"` / `"unbalanced-quotes"` reason and a message that
+ *   names the operator and suggests the split.
+ * - **shell mode** (`interpreter: "sh"`): the line is parsed and every
+ *   simple command — inside `;`, `&&`, `||`, pipes, subshells, `$( )`,
+ *   backticks and here-documents — is checked; redirection targets and `cd`
+ *   directories must stay in the jail (checked lexically here; `exec`
+ *   re-checks them with symlinks resolved).
+ *
+ * Every argv goes through `deny` (case-insensitive, wins), `allow`
+ * (exhaustive when non-empty), `denyPatterns` and `allowCommand`.
+ * Wrappers (`env`, `time`, `timeout`, `nice`, `nohup`, `command`,
+ * `builtin`, `exec`) and `find -exec` are followed to the command they run.
+ * A runner the policy cannot see into (`bash -c`, `eval`, `xargs`, `sudo`,
+ * …) is refused while the policy has deny rules, unless `allow` names it.
+ *
+ * @example
+ * checkShellCommand({ cwd, shell: { allow: ["git"] } }, "git add -A && git commit -m wip");
+ * // { allowed: false, reason: "metacharacter", message: "`&&` is not supported in argv mode: run `git add -A`, then `git commit -m wip`, …" }
+ */
+declare function checkShellCommand(policy: WorkspacePolicy, command: string): WorkspaceShellCheck;
+//#endregion
+export { WorkspaceShellCheck, WorkspaceShellPath, WorkspaceShellPathAccess, checkShellCommand };
+//# sourceMappingURL=shell-check.d.mts.map

package/esm/policy/shell-check.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-check.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/policy/shell-check.ts"],"mappings":";;;;;KAmBY,wBAAA;AAAZ;AAAA,UAGiB,kBAAA;;EAEf,IAAA;EALkC;EAOlC,MAAA,EAAQ,wBAAwB;EAJC;EAMjC,MAAA;AAAA;;;;;UAOe,mBAAA;EAPT;EASN,OAAA;EAFkC;EAIlC,MAAA,GAAS,2BAAA;EAUgB;EARzB,OAAA;EAFA;EAIA,UAAA;EAFA;EAIA,IAAA;EAAA;EAEA,QAAA;EAEA;EAAA,KAAA,EAAO,kBAAkB;AAAA;;AA6hCqE;;;;;;;;;;;;;;;;;;;;;;;;iBAAhF,iBAAA,CAAkB,MAAA,EAAQ,eAAA,EAAiB,OAAA,WAAkB,mBAAmB"}