@jitsusama/agentic-harness.core 0.1.0

package/dist/exec/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Running a command, as a dependency rather than an import.
+ *
+ * The whole surface is one type, one result shape and one helper that throws with
+ * the backend's own words. It is its own module because two libraries need it and
+ * neither owns it.
+ */
+export { type Exec, type ExecResult, type ProviderDeps, run, } from "./exec.js";

package/dist/exec/index.js

@@ -0,0 +1,8 @@
+/**
+ * Running a command, as a dependency rather than an import.
+ *
+ * The whole surface is one type, one result shape and one helper that throws with
+ * the backend's own words. It is its own module because two libraries need it and
+ * neither owns it.
+ */
+export { run, } from "./exec.js";

package/dist/gate/decision.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The generalized loop breaker. A gate blocks a violation set
+ * the first time it sees it, but relents if the identical set
+ * comes back, on the theory that an author who could not satisfy
+ * the rule after one specific, skill-grounded retry will not
+ * satisfy it on the next either. Relenting surfaces the
+ * violations to the human gate rather than trapping the author
+ * in a loop.
+ *
+ * The mechanism is domain-neutral: prose violations and section
+ * violations both flow through it, each supplying its own
+ * detection, its own block message and its own relent wording.
+ */
+/** A single convention violation that can be signed and gated. */
+export interface Violation {
+    /** Which rule was broken (the signature's namespace). */
+    readonly kind: string;
+    /** The offending text, used in the signature and the message. */
+    readonly found: string;
+}
+/** allow: clean. block: first offence. relent: already blocked once. */
+export type GateAction = "allow" | "block" | "relent";
+/** The gate's verdict on one artifact. */
+export interface GateDecision {
+    readonly action: GateAction;
+    /** Stable signature of this violation set, for the caller to persist. */
+    readonly signature: string;
+    /** Message for the AI (block) or the user (relent); empty when allowed. */
+    readonly message: string;
+}
+/**
+ * A stable, order-independent signature of a violation set,
+ * scoped to the artifact it was found in. The found text is
+ * lower-cased so a recurrence that only changes case is still
+ * recognized as the same violation, and the artifact is folded
+ * in (as a hash) so the same violation shape in two different
+ * bodies signs differently. Without the artifact scope, every
+ * single-emdash body collapses to the signature `emdash:—`, so
+ * blocking one artifact would relent the next unrelated one on
+ * its first fire. The relent is meant to break a loop on the
+ * identical resubmission, not to wave through a fresh artifact
+ * that happens to share a violation shape.
+ */
+export declare function violationSignature(violations: Violation[], artifact?: string): string;
+/**
+ * Decide whether to block, relent or allow a violation set given
+ * the signatures already blocked this session. format renders
+ * the block body; relentPrefix is prepended to that body when
+ * the gate relents, to explain why the violation is being let
+ * through.
+ */
+export declare function decideGate<T extends Violation>(violations: T[], priorSignatures: string[], format: (violations: T[]) => string, relentPrefix: string, artifact: string): GateDecision;

package/dist/gate/decision.js

@@ -0,0 +1,68 @@
+/**
+ * The generalized loop breaker. A gate blocks a violation set
+ * the first time it sees it, but relents if the identical set
+ * comes back, on the theory that an author who could not satisfy
+ * the rule after one specific, skill-grounded retry will not
+ * satisfy it on the next either. Relenting surfaces the
+ * violations to the human gate rather than trapping the author
+ * in a loop.
+ *
+ * The mechanism is domain-neutral: prose violations and section
+ * violations both flow through it, each supplying its own
+ * detection, its own block message and its own relent wording.
+ */
+/**
+ * A small, stable, non-cryptographic string hash (djb2). Used to
+ * fingerprint the artifact so the signature can be scoped to it
+ * without storing the whole body. A collision only ever causes a
+ * benign spurious relent, never a wrong block, so 32 bits is
+ * ample.
+ */
+function hashString(text) {
+    let hash = 5381;
+    for (let i = 0; i < text.length; i++) {
+        hash = (Math.imul(hash, 33) + text.charCodeAt(i)) | 0;
+    }
+    return (hash >>> 0).toString(36);
+}
+/**
+ * A stable, order-independent signature of a violation set,
+ * scoped to the artifact it was found in. The found text is
+ * lower-cased so a recurrence that only changes case is still
+ * recognized as the same violation, and the artifact is folded
+ * in (as a hash) so the same violation shape in two different
+ * bodies signs differently. Without the artifact scope, every
+ * single-emdash body collapses to the signature `emdash:—`, so
+ * blocking one artifact would relent the next unrelated one on
+ * its first fire. The relent is meant to break a loop on the
+ * identical resubmission, not to wave through a fresh artifact
+ * that happens to share a violation shape.
+ */
+export function violationSignature(violations, artifact) {
+    const body = violations
+        .map((v) => `${v.kind}:${v.found.toLowerCase()}`)
+        .sort()
+        .join("|");
+    return artifact ? `${hashString(artifact)}#${body}` : body;
+}
+/**
+ * Decide whether to block, relent or allow a violation set given
+ * the signatures already blocked this session. format renders
+ * the block body; relentPrefix is prepended to that body when
+ * the gate relents, to explain why the violation is being let
+ * through.
+ */
+export function decideGate(violations, priorSignatures, format, relentPrefix, artifact) {
+    if (violations.length === 0) {
+        return { action: "allow", signature: "", message: "" };
+    }
+    const signature = violationSignature(violations, artifact);
+    if (priorSignatures.includes(signature)) {
+        return {
+            action: "relent",
+            signature,
+            message: relentPrefix + format(violations),
+        };
+    }
+    return { action: "block", signature, message: format(violations) };
+}

package/dist/gate/deps.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The signature store contract a gate reads and writes. The
+ * loop breaker in decision.ts needs to know which violation
+ * signatures it has already blocked this session; this is the
+ * interface that supplies them, kept pure so the decision logic
+ * stays free of any session or runtime dependency. The
+ * session-backed implementation lives in lib/internal/gate.
+ */
+export interface GateDeps {
+    /** Every block signature recorded this session. */
+    readSignatures: () => string[];
+    /** Record a new block signature. */
+    persistSignature: (signature: string) => void;
+}

package/dist/gate/deps.js

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

package/dist/gate/index.d.ts

@@ -0,0 +1,2 @@
+export { decideGate, type GateAction, type GateDecision, type Violation, violationSignature, } from "./decision.js";
+export type { GateDeps } from "./deps.js";

package/dist/gate/index.js

@@ -0,0 +1 @@
+export { decideGate, violationSignature, } from "./decision.js";

package/dist/git-cli/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Git CLI violation detection: patterns that should be
+ * blocked before reaching guardians.
+ *
+ * - Amend ban: `git commit --amend` is blocked
+ *   unconditionally (git-commit-convention skill).
+ * - Unquoted heredoc: `<<EOF` instead of `<<'EOF'`
+ *   allows variable expansion that corrupts content
+ *   (commit-format skill).
+ * - Compound commands: multiple guardable targets or
+ *   state changes mixed with guardable commands are
+ *   blocked so guardians can process each independently
+ *   (commit-format skill).
+ *
+ * Every message here states the corrective action itself. They
+ * used to end by naming a skill to go and read, which is only
+ * actionable while that skill is loaded, and one of them named a
+ * skill whose worked example the next check blocked.
+ *
+ * The git add + git commit pattern is explicitly allowed
+ * because git add is a staging prefix, not a guardable target.
+ */
+/**
+ * Block `git commit --amend` unconditionally. Amends
+ * rewrite history and are almost never the right choice
+ * when the agent can just make a new commit.
+ */
+export declare function detectAmendViolation(stripped: string): string | null;
+/**
+ * Block `git commit` with an unquoted heredoc delimiter.
+ * Takes the stripped command (for git commit scoping) and
+ * the original (for heredoc operator validation).
+ */
+export declare function detectUnquotedCommitHeredoc(stripped: string, original: string): string | null;
+/**
+ * Check whether a bash command chains multiple concerns that
+ * should be separate calls. Returns a block reason or null
+ * if the command is fine.
+ */
+export declare function detectCompoundViolation(stripped: string): string | null;
+/**
+ * Run every git-cli check against a raw bash command. Returns the
+ * first violation's block reason, or null if the command is fine.
+ * The one entry point an adapter needs; the individual `detect*`
+ * functions stay exported for adapters that want finer control.
+ */
+export declare function checkGitCli(command: string): string | null;

package/dist/git-cli/index.js

@@ -0,0 +1,127 @@
+/**
+ * Git CLI violation detection: patterns that should be
+ * blocked before reaching guardians.
+ *
+ * - Amend ban: `git commit --amend` is blocked
+ *   unconditionally (git-commit-convention skill).
+ * - Unquoted heredoc: `<<EOF` instead of `<<'EOF'`
+ *   allows variable expansion that corrupts content
+ *   (commit-format skill).
+ * - Compound commands: multiple guardable targets or
+ *   state changes mixed with guardable commands are
+ *   blocked so guardians can process each independently
+ *   (commit-format skill).
+ *
+ * Every message here states the corrective action itself. They
+ * used to end by naming a skill to go and read, which is only
+ * actionable while that skill is loaded, and one of them named a
+ * skill whose worked example the next check blocked.
+ *
+ * The git add + git commit pattern is explicitly allowed
+ * because git add is a staging prefix, not a guardable target.
+ */
+import { hasUnquotedHeredoc, stripHeredocBodies, stripShellData, } from "../shell/parse.js";
+/** Commands that guardians intercept and may rewrite. */
+const GUARDABLE_PATTERNS = [
+    /\bgit\s+commit\b/,
+    /\bgh\s+pr\s+(?:create|edit)\b/,
+    /\bgh\s+issue\s+(?:create|edit)\b/,
+];
+/**
+ * Git state changes that shouldn't be chained with guardable
+ * commands. These alter repo state in ways the subsequent
+ * command depends on, and a guardian rewrite could drop them.
+ */
+const STATE_CHANGE_PATTERNS = [
+    /\bgit\s+push\b/,
+    /\bgit\s+checkout\b/,
+    /\bgit\s+switch\b/,
+    /\bgit\s+pull\b/,
+    /\bgit\s+merge\b/,
+    /\bgit\s+rebase\b/,
+    /\bgit\s+reset\b/,
+    /\bgit\s+stash\b/,
+    /\bgit\s+fetch\b/,
+];
+/** Shell separators that divide independent commands. */
+const SEPARATOR = /\s*(?:&&|;|\n)\s*/;
+/**
+ * Block `git commit --amend` unconditionally. Amends
+ * rewrite history and are almost never the right choice
+ * when the agent can just make a new commit.
+ */
+export function detectAmendViolation(stripped) {
+    if (/\bgit\s+commit\b/.test(stripped) && /--amend\b/.test(stripped)) {
+        return ("Blocked: --amend is not allowed. Make a new commit " +
+            "instead.\n\n" +
+            "Amending rewrites history and is almost never necessary. " +
+            "A new commit is cleaner and preserves the work trail.");
+    }
+    return null;
+}
+/**
+ * Block `git commit` with an unquoted heredoc delimiter.
+ * Takes the stripped command (for git commit scoping) and
+ * the original (for heredoc operator validation).
+ */
+export function detectUnquotedCommitHeredoc(stripped, original) {
+    if (!/\bgit\s+commit\b/.test(stripped))
+        return null;
+    if (!hasUnquotedHeredoc(original))
+        return null;
+    return ("Blocked: heredoc uses an unquoted delimiter (e.g. " +
+        "`<<EOF`), which allows shell variable expansion. " +
+        "Use a quoted delimiter (`<<'EOF'`) to prevent " +
+        "`$variable` and backtick expansion from corrupting " +
+        "the commit message:\n\n" +
+        "git commit -F- <<'EOF'\n" +
+        "type(scope): subject\n\nWhy, not what.\nEOF");
+}
+/**
+ * Check whether a bash command chains multiple concerns that
+ * should be separate calls. Returns a block reason or null
+ * if the command is fine.
+ */
+export function detectCompoundViolation(stripped) {
+    const segments = stripped.split(SEPARATOR).filter(Boolean);
+    if (segments.length < 2)
+        return null;
+    let guardableCount = 0;
+    let stateChangeCount = 0;
+    for (const segment of segments) {
+        const trimmed = segment.trim();
+        if (GUARDABLE_PATTERNS.some((p) => p.test(trimmed))) {
+            guardableCount++;
+            continue;
+        }
+        if (STATE_CHANGE_PATTERNS.some((p) => p.test(trimmed))) {
+            stateChangeCount++;
+        }
+    }
+    if (guardableCount > 1) {
+        return ("Blocked: multiple guardable commands in one bash call. " +
+            "Each git commit, gh pr create/edit and gh issue create/edit " +
+            "must be its own bash call so guardians can review them " +
+            "independently. Retry with one command per bash call.");
+    }
+    if (guardableCount > 0 && stateChangeCount > 0) {
+        return ("Blocked: git state change chained with a guardable command. " +
+            "Commands like git push, git checkout and git pull must be " +
+            "separate bash calls from git commit, gh pr create/edit and " +
+            "gh issue create/edit. Retry with one command per bash call.");
+    }
+    return null;
+}
+/**
+ * Run every git-cli check against a raw bash command. Returns the
+ * first violation's block reason, or null if the command is fine.
+ * The one entry point an adapter needs; the individual `detect*`
+ * functions stay exported for adapters that want finer control.
+ */
+export function checkGitCli(command) {
+    const stripped = stripShellData(stripHeredocBodies(command));
+    return (detectAmendViolation(stripped) ??
+        detectUnquotedCommitHeredoc(stripped, command) ??
+        detectCompoundViolation(stripped) ??
+        null);
+}

package/dist/github-cli/command-spec.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Flag specs for the gh commands this package understands, defined
+ * once in the domain that owns them and imported wherever a
+ * consumer needs to read a gh flag (attribution, the interceptor).
+ * The generic command model ships no flag tables; callers pass
+ * these in.
+ */
+import type { FlagSpec } from "../command/index.js";
+/**
+ * The body flags of gh pr/issue create and edit: the inline body
+ * (--body, -b) and the body file (--body-file, -F), in both their
+ * long and short forms.
+ */
+export declare const GH_BODY_SPEC: FlagSpec;

package/dist/github-cli/command-spec.js

@@ -0,0 +1,18 @@
+/**
+ * Flag specs for the gh commands this package understands, defined
+ * once in the domain that owns them and imported wherever a
+ * consumer needs to read a gh flag (attribution, the interceptor).
+ * The generic command model ships no flag tables; callers pass
+ * these in.
+ */
+/**
+ * The body flags of gh pr/issue create and edit: the inline body
+ * (--body, -b) and the body file (--body-file, -F), in both their
+ * long and short forms.
+ */
+export const GH_BODY_SPEC = {
+    flags: [
+        { name: "body", long: "body", short: "b", takesValue: true },
+        { name: "body-file", long: "body-file", short: "F", takesValue: true },
+    ],
+};

package/dist/github-cli/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Detects gh pr/issue commands that violate the
+ * github-cli-convention skill's formatting rules.
+ *
+ * The convention requires heredoc syntax (--body-file -)
+ * with a quoted delimiter for body content, and metadata
+ * assignment in separate commands after creation.
+ */
+export { GH_BODY_SPEC } from "./command-spec.js";
+/**
+ * Check whether a gh command uses --body instead of
+ * --body-file with heredoc. Returns a block reason or
+ * null if the command is fine.
+ */
+export declare function detectInlineBody(command: string): string | null;
+/**
+ * Refuse `gh pr merge --delete-branch`.
+ *
+ * The flag deletes the branch through a separate API call, and GitHub auto-closes
+ * every open PR that used it as a base. Those cannot be reopened, so a stacked PR
+ * merged this way destroys the rest of the stack with no way back. The flag saves one
+ * command and the failure is unrecoverable, which is the trade a gate exists for.
+ *
+ * Blocked whether or not anything is stacked on it, because the interceptor cannot
+ * know that from the command, and the safe sequence costs one extra call. This rule
+ * used to live in a skill, where it was correct and unenforced.
+ */
+export declare function detectDeleteBranchOnMerge(command: string): string | null;
+/**
+ * Check whether a gh create command packs metadata flags
+ * that should be in separate edit commands. Returns a block
+ * reason or null if the command is fine.
+ */
+export declare function detectPackedMetadata(command: string): string | null;
+/**
+ * Check whether a gh command uses --body-file with a file
+ * path instead of stdin. The convention requires
+ * `--body-file -` piped from a heredoc, never a file path.
+ */
+export declare function detectBodyFilePath(command: string): string | null;
+/**
+ * Check whether a gh command uses --body-file - but has no
+ * heredoc to feed it. Without a heredoc, the command hangs
+ * waiting for stdin.
+ *
+ * Takes both the stripped command (for gh scoping and
+ * --body-file detection) and the original (for heredoc
+ * presence, since stripping removes the operator).
+ */
+export declare function detectMissingHeredoc(stripped: string, original: string): string | null;
+/**
+ * Check whether a gh command uses a heredoc with an unquoted
+ * delimiter. Unquoted delimiters allow shell variable expansion
+ * (`$variable`, backticks, `$(command)`) which corrupts body
+ * content.
+ *
+ * Takes both the stripped command (for gh scoping) and the
+ * original (for heredoc operator validation, which stripping
+ * would remove).
+ */
+export declare function detectUnsafeHeredoc(stripped: string, original: string): string | null;
+/**
+ * Run every github-cli check against a raw bash command. Returns
+ * the first violation's block reason, or null if the command is
+ * fine. The one entry point an adapter needs; the individual
+ * `detect*` functions stay exported for adapters that want finer
+ * control.
+ */
+export declare function checkGithubCli(command: string): string | null;
+/** Detect whether a bash command contains a specific gh subcommand. */
+export declare function isGhCommand(command: string, subcommand: string): boolean;

package/dist/github-cli/index.js

@@ -0,0 +1,188 @@
+/**
+ * Detects gh pr/issue commands that violate the
+ * github-cli-convention skill's formatting rules.
+ *
+ * The convention requires heredoc syntax (--body-file -)
+ * with a quoted delimiter for body content, and metadata
+ * assignment in separate commands after creation.
+ */
+import { findFlag, tokenize } from "../command/index.js";
+import { extractBodyFilePath, hasUnquotedHeredoc, stripHeredocBodies, stripShellData, } from "../shell/parse.js";
+import { GH_BODY_SPEC } from "./command-spec.js";
+export { GH_BODY_SPEC } from "./command-spec.js";
+/**
+ * The form every one of these blocks is asking for, written out.
+ *
+ * Here rather than in the skill it came from, because a block that names a rule and
+ * sends the reader elsewhere for the fix is only actionable while the elsewhere is
+ * loaded. Four of these messages used to end with "read the github-cli-convention
+ * skill for the heredoc pattern", which is a redirect to a document the reader may
+ * not have and cannot be sure of. The pattern is three lines. It fits here.
+ */
+const REQUIRED_FORM = "The required form is:\n\n" +
+    "gh pr create --title '...' --body-file - <<'EOF'\n" +
+    "### \u{1F310} Situation\n...\nEOF\n\n" +
+    "A quoted delimiter, stdin rather than a path, and nothing piped or wrapped " +
+    "around the command.";
+/** Matches gh pr or issue create/edit commands. */
+const GH_ENTITY_COMMAND = /\bgh\s+(?:pr|issue)\s+(?:create|edit)\b/;
+/** Matches --body-file - (stdin). */
+const BODY_FILE_STDIN = /--body-file\s+-(?:\s|$)/;
+/** Matches a heredoc operator. */
+const HEREDOC = /<<-?\s*['"]?\w/;
+/**
+ * Metadata flags that should be in separate edit commands,
+ * not packed into create.
+ */
+const METADATA_FLAGS = /--(?:add-)?(?:label|assignee|reviewer|project)\b|--milestone\b/;
+/** Matches a gh create (not edit) command. */
+const GH_CREATE = /\bgh\s+(?:pr|issue)\s+create\b/;
+/**
+ * Check whether a gh command uses --body instead of
+ * --body-file with heredoc. Returns a block reason or
+ * null if the command is fine.
+ */
+export function detectInlineBody(command) {
+    const gh = findGhEntityCommand(command);
+    if (!gh)
+        return null;
+    // The body-file heredoc form is the correct one; only an inline
+    // body (--body or its short -b) is the violation.
+    if (gh.heredoc)
+        return null;
+    if (findFlag(gh, GH_BODY_SPEC, "body-file"))
+        return null;
+    if (!findFlag(gh, GH_BODY_SPEC, "body"))
+        return null;
+    return ("Blocked: gh pr/issue command uses an inline body (--body or " +
+        "-b) instead of --body-file with a heredoc. An inline body has " +
+        `quoting issues with markdown content.\n\n${REQUIRED_FORM}`);
+}
+/**
+ * Refuse `gh pr merge --delete-branch`.
+ *
+ * The flag deletes the branch through a separate API call, and GitHub auto-closes
+ * every open PR that used it as a base. Those cannot be reopened, so a stacked PR
+ * merged this way destroys the rest of the stack with no way back. The flag saves one
+ * command and the failure is unrecoverable, which is the trade a gate exists for.
+ *
+ * Blocked whether or not anything is stacked on it, because the interceptor cannot
+ * know that from the command, and the safe sequence costs one extra call. This rule
+ * used to live in a skill, where it was correct and unenforced.
+ */
+export function detectDeleteBranchOnMerge(command) {
+    if (!/\bgh\s+pr\s+merge\b/.test(command))
+        return null;
+    if (!/(?:--delete-branch|(?<![\w-])-d(?![\w-]))/.test(command))
+        return null;
+    return ("Blocked: --delete-branch on a merge deletes the branch through a " +
+        "separate API call, and GitHub permanently closes every open PR that " +
+        "used it as a base. Closed that way, they cannot be reopened.\n\n" +
+        "Merge without it, then delete the branch once you have confirmed " +
+        "nothing is based on it:\n\n" +
+        "gh pr merge <number> --merge\n" +
+        "gh pr list --base <branch>   # empty means nothing depends on it\n" +
+        "git push origin --delete <branch>\n\n" +
+        "Prefer `review_offer merge`, which does not offer the flag at all.");
+}
+/** Find a gh pr/issue create or edit command in a bash command. */
+function findGhEntityCommand(command) {
+    return tokenize(command).commands.find((c) => c.argv[0]?.text === "gh" &&
+        (c.argv[1]?.text === "pr" || c.argv[1]?.text === "issue") &&
+        (c.argv[2]?.text === "create" || c.argv[2]?.text === "edit"));
+}
+/**
+ * Check whether a gh create command packs metadata flags
+ * that should be in separate edit commands. Returns a block
+ * reason or null if the command is fine.
+ */
+export function detectPackedMetadata(command) {
+    if (!GH_CREATE.test(command))
+        return null;
+    if (!METADATA_FLAGS.test(command))
+        return null;
+    return ("Blocked: gh create command includes metadata flags " +
+        "(labels, assignees, reviewers, milestones, projects). " +
+        "Assign metadata in separate gh edit commands after " +
+        "creation, one concern per call:\n\n" +
+        "gh pr edit <number> --add-label bug\n" +
+        "gh pr edit <number> --add-assignee someone");
+}
+/**
+ * Check whether a gh command uses --body-file with a file
+ * path instead of stdin. The convention requires
+ * `--body-file -` piped from a heredoc, never a file path.
+ */
+export function detectBodyFilePath(command) {
+    if (!GH_ENTITY_COMMAND.test(command))
+        return null;
+    const path = extractBodyFilePath(command);
+    if (!path)
+        return null;
+    return ("Blocked: --body-file points to a file path " +
+        `(${path}) instead of stdin. Use \`--body-file -\` ` +
+        `with a heredoc to pipe the body content.\n\n${REQUIRED_FORM}`);
+}
+/**
+ * Check whether a gh command uses --body-file - but has no
+ * heredoc to feed it. Without a heredoc, the command hangs
+ * waiting for stdin.
+ *
+ * Takes both the stripped command (for gh scoping and
+ * --body-file detection) and the original (for heredoc
+ * presence, since stripping removes the operator).
+ */
+export function detectMissingHeredoc(stripped, original) {
+    if (!GH_ENTITY_COMMAND.test(stripped))
+        return null;
+    if (!BODY_FILE_STDIN.test(stripped))
+        return null;
+    if (HEREDOC.test(original))
+        return null;
+    return ("Blocked: --body-file - has no heredoc to provide the " +
+        "body content. The command will hang waiting for stdin.\n\n" +
+        `Add a heredoc after the command.\n\n${REQUIRED_FORM}`);
+}
+/**
+ * Check whether a gh command uses a heredoc with an unquoted
+ * delimiter. Unquoted delimiters allow shell variable expansion
+ * (`$variable`, backticks, `$(command)`) which corrupts body
+ * content.
+ *
+ * Takes both the stripped command (for gh scoping) and the
+ * original (for heredoc operator validation, which stripping
+ * would remove).
+ */
+export function detectUnsafeHeredoc(stripped, original) {
+    if (!GH_ENTITY_COMMAND.test(stripped))
+        return null;
+    if (!hasUnquotedHeredoc(original))
+        return null;
+    return ("Blocked: heredoc uses an unquoted delimiter (e.g. " +
+        "`<<EOF`), which allows shell variable expansion. " +
+        "Use a quoted delimiter (`<<'EOF'`) to prevent " +
+        "`$variable` and backtick expansion from corrupting " +
+        `the body content.\n\n${REQUIRED_FORM}`);
+}
+/**
+ * Run every github-cli check against a raw bash command. Returns
+ * the first violation's block reason, or null if the command is
+ * fine. The one entry point an adapter needs; the individual
+ * `detect*` functions stay exported for adapters that want finer
+ * control.
+ */
+export function checkGithubCli(command) {
+    const stripped = stripShellData(stripHeredocBodies(command));
+    return (detectInlineBody(command) ??
+        detectPackedMetadata(stripped) ??
+        detectDeleteBranchOnMerge(stripped) ??
+        detectBodyFilePath(stripped) ??
+        detectMissingHeredoc(stripped, command) ??
+        detectUnsafeHeredoc(stripped, command) ??
+        null);
+}
+/** Detect whether a bash command contains a specific gh subcommand. */
+export function isGhCommand(command, subcommand) {
+    const re = new RegExp(`\\bgh\\s+${subcommand}\\s+(create|edit)\\b`);
+    return re.test(command);
+}