vouchington-tooling 0.59.0 → 0.60.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -0
- package/dist/cli/commands/hook.d.mts +2 -0
- package/dist/cli/commands/hook.mjs +19 -0
- package/dist/cli/index.mjs +6 -0
- package/dist/cli/parse-forwarded-commands.d.mts +6 -0
- package/dist/cli/parse-forwarded-commands.mjs +4 -0
- package/dist/cli/parse.d.mts +6 -0
- package/dist/cli/usage-text.d.mts +1 -0
- package/dist/cli/usage-text.mjs +170 -0
- package/dist/cli/usage.d.mts +2 -1
- package/dist/cli/usage.mjs +2 -156
- package/dist/command-policy/engine.d.mts +7 -0
- package/dist/command-policy/engine.mjs +58 -0
- package/dist/command-policy/git-patterns.d.mts +20 -0
- package/dist/command-policy/git-patterns.mjs +82 -0
- package/dist/command-policy/git-process.d.mts +4 -0
- package/dist/command-policy/git-process.mjs +54 -0
- package/dist/command-policy/github-checkout-owners.d.mts +22 -0
- package/dist/command-policy/github-checkout-owners.mjs +122 -0
- package/dist/command-policy/github-command-context.d.mts +6 -0
- package/dist/command-policy/github-command-context.mjs +19 -0
- package/dist/command-policy/github-command-cwd.d.mts +8 -0
- package/dist/command-policy/github-command-cwd.mjs +130 -0
- package/dist/command-policy/github-command-position.d.mts +7 -0
- package/dist/command-policy/github-command-position.mjs +12 -0
- package/dist/command-policy/github-configured-base.d.mts +25 -0
- package/dist/command-policy/github-configured-base.mjs +59 -0
- package/dist/command-policy/github-invocation.d.mts +9 -0
- package/dist/command-policy/github-invocation.mjs +80 -0
- package/dist/command-policy/github-merge-authority.d.mts +21 -0
- package/dist/command-policy/github-merge-authority.mjs +86 -0
- package/dist/command-policy/github-option-flags.d.mts +3 -0
- package/dist/command-policy/github-option-flags.mjs +67 -0
- package/dist/command-policy/github-options.d.mts +12 -0
- package/dist/command-policy/github-options.mjs +73 -0
- package/dist/command-policy/github-stack-workflow.d.mts +9 -0
- package/dist/command-policy/github-stack-workflow.mjs +94 -0
- package/dist/command-policy/github-workflow.d.mts +7 -0
- package/dist/command-policy/github-workflow.mjs +50 -0
- package/dist/command-policy/hook/args.d.mts +11 -0
- package/dist/command-policy/hook/args.mjs +49 -0
- package/dist/command-policy/hook/harness.d.mts +26 -0
- package/dist/command-policy/hook/harness.mjs +119 -0
- package/dist/command-policy/hook/policy-module.d.mts +7 -0
- package/dist/command-policy/hook/policy-module.mjs +48 -0
- package/dist/command-policy/hook/post-tool-use.d.mts +9 -0
- package/dist/command-policy/hook/post-tool-use.mjs +51 -0
- package/dist/command-policy/hook/pre-tool-use.d.mts +21 -0
- package/dist/command-policy/hook/pre-tool-use.mjs +45 -0
- package/dist/command-policy/hook/run.d.mts +17 -0
- package/dist/command-policy/hook/run.mjs +69 -0
- package/dist/command-policy/hook/types.d.mts +33 -0
- package/dist/command-policy/hook/types.mjs +5 -0
- package/dist/command-policy/index.d.mts +29 -0
- package/dist/command-policy/index.mjs +23 -0
- package/dist/command-policy/path-references.d.mts +14 -0
- package/dist/command-policy/path-references.mjs +68 -0
- package/dist/command-policy/path-rules.d.mts +11 -0
- package/dist/command-policy/path-rules.mjs +37 -0
- package/dist/command-policy/payload.d.mts +8 -0
- package/dist/command-policy/payload.mjs +54 -0
- package/dist/command-policy/types.d.mts +77 -0
- package/dist/command-policy/types.mjs +1 -0
- package/dist/index.d.mts +2 -0
- package/dist/index.mjs +1 -0
- package/dist/tmux/cli-shared.d.mts +18 -0
- package/dist/tmux/cli-shared.mjs +8 -0
- package/dist/tmux/cli.d.mts +3 -0
- package/dist/tmux/cli.mjs +34 -0
- package/dist/tmux/config.d.mts +24 -0
- package/dist/tmux/config.mjs +91 -0
- package/dist/tmux/fake-tmux.test-helpers.d.mts +46 -0
- package/dist/tmux/fake-tmux.test-helpers.mjs +105 -0
- package/dist/tmux/hook-payload.d.mts +8 -0
- package/dist/tmux/hook-payload.mjs +39 -0
- package/dist/tmux/index.d.mts +9 -0
- package/dist/tmux/index.mjs +7 -0
- package/dist/tmux/launcher.d.mts +11 -0
- package/dist/tmux/launcher.mjs +127 -0
- package/dist/tmux/reminder-post-tool.d.mts +21 -0
- package/dist/tmux/reminder-post-tool.mjs +88 -0
- package/dist/tmux/runner.d.mts +11 -0
- package/dist/tmux/runner.mjs +26 -0
- package/dist/tmux/session-name.d.mts +5 -0
- package/dist/tmux/session-name.mjs +10 -0
- package/dist/tmux/shell-quote.d.mts +9 -0
- package/dist/tmux/shell-quote.mjs +16 -0
- package/dist/tmux/up.d.mts +2 -0
- package/dist/tmux/up.mjs +73 -0
- package/dist/tmux/windows.d.mts +18 -0
- package/dist/tmux/windows.mjs +50 -0
- package/package.json +11 -1
- package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
- package/scripts/tmux/tmux-agent-reminder.sh +68 -0
- package/scripts/tmux/tmux-name.sh +34 -0
- package/scripts/tmux/tmux-read-title.sh +13 -0
- package/scripts/tmux/tmux-target.sh +130 -0
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
export function isRecord(value) {
|
|
2
|
+
return typeof value === 'object' && value !== null;
|
|
3
|
+
}
|
|
4
|
+
export function hookToolInput(payload) {
|
|
5
|
+
if (isRecord(payload.tool_input))
|
|
6
|
+
return payload.tool_input;
|
|
7
|
+
if (isRecord(payload.toolInput))
|
|
8
|
+
return payload.toolInput;
|
|
9
|
+
return undefined;
|
|
10
|
+
}
|
|
11
|
+
export function extractToolCommand(payload) {
|
|
12
|
+
const toolInput = hookToolInput(payload);
|
|
13
|
+
if (toolInput && typeof toolInput.command === 'string')
|
|
14
|
+
return toolInput.command;
|
|
15
|
+
if (typeof payload.command === 'string')
|
|
16
|
+
return payload.command;
|
|
17
|
+
return '';
|
|
18
|
+
}
|
|
19
|
+
function firstString(values) {
|
|
20
|
+
for (const value of values) {
|
|
21
|
+
if (typeof value === 'string' && value.trim() !== '')
|
|
22
|
+
return value.trim();
|
|
23
|
+
}
|
|
24
|
+
return '';
|
|
25
|
+
}
|
|
26
|
+
export function hookToolName(payload) {
|
|
27
|
+
return firstString([payload.tool_name, payload.toolName]);
|
|
28
|
+
}
|
|
29
|
+
export function hookSessionId(payload) {
|
|
30
|
+
return firstString([payload.session_id, payload.sessionId, payload.conversation_id]);
|
|
31
|
+
}
|
|
32
|
+
export function hookFilePath(payload) {
|
|
33
|
+
if (typeof payload.file_path === 'string' && payload.file_path !== '')
|
|
34
|
+
return payload.file_path;
|
|
35
|
+
if (typeof payload.filePath === 'string' && payload.filePath !== '')
|
|
36
|
+
return payload.filePath;
|
|
37
|
+
const toolInput = hookToolInput(payload);
|
|
38
|
+
if (!toolInput)
|
|
39
|
+
return '';
|
|
40
|
+
for (const key of ['file_path', 'filePath', 'path']) {
|
|
41
|
+
const value = toolInput[key];
|
|
42
|
+
if (typeof value === 'string' && value !== '')
|
|
43
|
+
return value;
|
|
44
|
+
}
|
|
45
|
+
return '';
|
|
46
|
+
}
|
|
47
|
+
export function hookCwd(payload, fallback = process.cwd()) {
|
|
48
|
+
const toolInput = hookToolInput(payload);
|
|
49
|
+
for (const value of [toolInput?.cwd, toolInput?.workdir, payload.cwd, payload.workspaceRoot]) {
|
|
50
|
+
if (typeof value === 'string' && value !== '')
|
|
51
|
+
return value;
|
|
52
|
+
}
|
|
53
|
+
return fallback;
|
|
54
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
export type HookPayload = {
|
|
2
|
+
tool_input?: unknown;
|
|
3
|
+
toolInput?: unknown;
|
|
4
|
+
session_id?: unknown;
|
|
5
|
+
sessionId?: unknown;
|
|
6
|
+
conversation_id?: unknown;
|
|
7
|
+
tool_name?: unknown;
|
|
8
|
+
toolName?: unknown;
|
|
9
|
+
command?: unknown;
|
|
10
|
+
cwd?: unknown;
|
|
11
|
+
workspaceRoot?: unknown;
|
|
12
|
+
[key: string]: unknown;
|
|
13
|
+
};
|
|
14
|
+
export type BlockDecision = {
|
|
15
|
+
reason: string;
|
|
16
|
+
/**
|
|
17
|
+
* 'block' (the default when omitted) rejects the tool call outright. 'confirm' marks an
|
|
18
|
+
* interactive lone merge, which a caller may render as a silent allow in an attended session.
|
|
19
|
+
* Only `findInteractiveMergeConfirm` produces 'confirm', and the engine consults it after every
|
|
20
|
+
* block, so a block anywhere in the command always wins.
|
|
21
|
+
*/
|
|
22
|
+
disposition?: 'block' | 'confirm';
|
|
23
|
+
};
|
|
24
|
+
export type PatternRule = {
|
|
25
|
+
pattern: RegExp;
|
|
26
|
+
reason: string;
|
|
27
|
+
};
|
|
28
|
+
/** Paths that automation must not write. Directory prefixes end in `/`. */
|
|
29
|
+
export type ProtectedPaths = {
|
|
30
|
+
dirPrefixes: readonly string[];
|
|
31
|
+
exactFiles: readonly string[];
|
|
32
|
+
reason: string;
|
|
33
|
+
};
|
|
34
|
+
/** A mistyped path segment (for example a misspelled dot-directory) and the reason to refuse it. */
|
|
35
|
+
export type PathTypoRule = {
|
|
36
|
+
segment: string;
|
|
37
|
+
reason: string;
|
|
38
|
+
};
|
|
39
|
+
/** Read-only git probes; every one returns undefined when git cannot answer. */
|
|
40
|
+
export type GitProbe = {
|
|
41
|
+
currentBranch(cwd: string): string | undefined;
|
|
42
|
+
configValue(cwd: string, key: string): string | undefined;
|
|
43
|
+
isAncestor(cwd: string, ancestor: string, descendant: string): boolean | undefined;
|
|
44
|
+
resolveRef(cwd: string, ref: string): string | undefined;
|
|
45
|
+
};
|
|
46
|
+
export type StackPolicy = {
|
|
47
|
+
/** Branch a stack must root on and a PR must target. Defaults to `main`. */
|
|
48
|
+
baseBranch?: string;
|
|
49
|
+
/** Remote whose `<remote>/<baseBranch>` HEAD must descend from. Defaults to `origin`. */
|
|
50
|
+
remote?: string;
|
|
51
|
+
/** Appended to stack reasons, for example a pointer to the repository's stacking skill. */
|
|
52
|
+
guidance?: string;
|
|
53
|
+
/** What to do after a draft PR opens, for example the description tool to call. */
|
|
54
|
+
draftFollowUp?: string;
|
|
55
|
+
/** Probe override for tests and sandboxes. */
|
|
56
|
+
git?: GitProbe;
|
|
57
|
+
};
|
|
58
|
+
export type CommandPolicy = {
|
|
59
|
+
typoPaths?: readonly PathTypoRule[];
|
|
60
|
+
protectedPaths?: ProtectedPaths;
|
|
61
|
+
/** Tested against every command and nested script, before the git rules. */
|
|
62
|
+
commandPatterns?: readonly PatternRule[];
|
|
63
|
+
/** Tested against nested scripts, only when the command mentions git. */
|
|
64
|
+
gitPatterns?: readonly PatternRule[];
|
|
65
|
+
/** Reason for an interactive `git rebase --continue`; omit to allow it. */
|
|
66
|
+
rebaseContinueReason?: string;
|
|
67
|
+
/** Appended to merge reasons, for example a pointer to the merge-authority document. */
|
|
68
|
+
mergeGuidance?: string;
|
|
69
|
+
/** GitHub stack rules apply only when this is present. */
|
|
70
|
+
stack?: StackPolicy;
|
|
71
|
+
};
|
|
72
|
+
export type EvaluateOptions = {
|
|
73
|
+
/** Whether the call runs in unattended automation. Defaults to true, the strict choice. */
|
|
74
|
+
automationContext?: boolean;
|
|
75
|
+
/** Directory the call runs in. Defaults to the payload's own, else `process.cwd()`. */
|
|
76
|
+
cwd?: string;
|
|
77
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/index.d.mts
CHANGED
|
@@ -111,3 +111,5 @@ export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffTh
|
|
|
111
111
|
export type { DiffLineChanges, LargeDiffThresholds } from './pull-request-diff/index.mts';
|
|
112
112
|
export { tokenizeShellWords, tokenizeShellWordsDetailed } from './shell-parse/index.mts';
|
|
113
113
|
export type { ShellWord } from './shell-parse/index.mts';
|
|
114
|
+
export { evaluateCommandPolicy } from './command-policy/index.mts';
|
|
115
|
+
export type { BlockDecision, CommandPolicy } from './command-policy/index.mts';
|
package/dist/index.mjs
CHANGED
|
@@ -60,3 +60,4 @@ export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadE
|
|
|
60
60
|
export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferences, parseNonClosingRefs, } from "./gh-cli/index.mjs";
|
|
61
61
|
export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from "./pull-request-diff/index.mjs";
|
|
62
62
|
export { tokenizeShellWords, tokenizeShellWordsDetailed } from "./shell-parse/index.mjs";
|
|
63
|
+
export { evaluateCommandPolicy } from "./command-policy/index.mjs";
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { ScriptSpawn } from '../cli/commands/spawn-script.mts';
|
|
2
|
+
import type { PaneTitleSpawn } from './reminder-post-tool.mts';
|
|
3
|
+
import type { TmuxRun } from './runner.mts';
|
|
4
|
+
export declare const TMUX_USAGE = "tmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name>\ntmux read-title\ntmux agent-reminder session-start|user-prompt\ntmux post-tool (hook payload on stdin)\n Environment: TMUX_TARGET_BIN (tmux binary), TMUX_TARGET_ROOT (worktree, default cwd),\n TMUX_NAME_COMMAND (rename command named in reminders), AGENT_TMUX_SOCKET/PANE/WORKTREE.\n";
|
|
5
|
+
export type TmuxCliDeps = {
|
|
6
|
+
env?: NodeJS.ProcessEnv;
|
|
7
|
+
cwd?: string;
|
|
8
|
+
spawn?: ScriptSpawn;
|
|
9
|
+
readStdin?: () => string;
|
|
10
|
+
tmux?: TmuxRun;
|
|
11
|
+
hasChildren?: (pid: string) => boolean;
|
|
12
|
+
sleep?: (milliseconds: number) => void;
|
|
13
|
+
spawnPaneTitle?: PaneTitleSpawn;
|
|
14
|
+
out?: (text: string) => void;
|
|
15
|
+
err?: (text: string) => void;
|
|
16
|
+
pid?: number;
|
|
17
|
+
isPidAlive?: (pid: number) => boolean;
|
|
18
|
+
};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export const TMUX_USAGE = `tmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]
|
|
2
|
+
tmux name [--socket PATH --pane %ID --worktree PATH] <name>
|
|
3
|
+
tmux read-title
|
|
4
|
+
tmux agent-reminder session-start|user-prompt
|
|
5
|
+
tmux post-tool (hook payload on stdin)
|
|
6
|
+
Environment: TMUX_TARGET_BIN (tmux binary), TMUX_TARGET_ROOT (worktree, default cwd),
|
|
7
|
+
TMUX_NAME_COMMAND (rename command named in reminders), AGENT_TMUX_SOCKET/PANE/WORKTREE.
|
|
8
|
+
`;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { runScript } from "../cli/commands/spawn-script.mjs";
|
|
3
|
+
import { packageScriptPath } from "../cli/script-path.mjs";
|
|
4
|
+
import { TMUX_USAGE } from "./cli-shared.mjs";
|
|
5
|
+
import { parseHookPayload } from "./hook-payload.mjs";
|
|
6
|
+
import { renderPostToolReminder } from "./reminder-post-tool.mjs";
|
|
7
|
+
import { runUp } from "./up.mjs";
|
|
8
|
+
export { TMUX_USAGE };
|
|
9
|
+
const SCRIPTS = {
|
|
10
|
+
name: 'scripts/tmux/tmux-name.sh',
|
|
11
|
+
'read-title': 'scripts/tmux/tmux-read-title.sh',
|
|
12
|
+
'agent-reminder': 'scripts/tmux/tmux-agent-reminder.sh',
|
|
13
|
+
};
|
|
14
|
+
export function runTmuxCommand(args, deps = {}) {
|
|
15
|
+
const [subcommand, ...rest] = args;
|
|
16
|
+
const script = subcommand === undefined ? undefined : SCRIPTS[subcommand];
|
|
17
|
+
if (script !== undefined)
|
|
18
|
+
return runScript('bash', packageScriptPath(script), rest, deps.spawn);
|
|
19
|
+
if (subcommand === 'up')
|
|
20
|
+
return runUp(rest, deps);
|
|
21
|
+
if (subcommand === 'post-tool' && rest.length === 0) {
|
|
22
|
+
const stdin = deps.readStdin ?? (() => readFileSync(0, 'utf8'));
|
|
23
|
+
const reminder = renderPostToolReminder(parseHookPayload(stdin()), {
|
|
24
|
+
env: deps.env,
|
|
25
|
+
spawnPaneTitle: deps.spawnPaneTitle,
|
|
26
|
+
});
|
|
27
|
+
if (reminder !== null)
|
|
28
|
+
(deps.out ?? ((text) => void process.stdout.write(text)))(`${reminder}\n`);
|
|
29
|
+
return 0;
|
|
30
|
+
}
|
|
31
|
+
;
|
|
32
|
+
(deps.err ?? ((text) => void process.stderr.write(text)))(`vouchington: expected: up|name|read-title|agent-reminder|post-tool\n${TMUX_USAGE}`);
|
|
33
|
+
return 2;
|
|
34
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export type TmuxWindowConfig = {
|
|
2
|
+
name: string;
|
|
3
|
+
/** Shell body run through `bash -lc`. */
|
|
4
|
+
command: string;
|
|
5
|
+
/** Working directory, relative to the worktree root unless absolute. */
|
|
6
|
+
cwd?: string;
|
|
7
|
+
env: Record<string, string>;
|
|
8
|
+
/** Keep the pane open after the command exits (appends `; read`). Default true. */
|
|
9
|
+
keepOpen: boolean;
|
|
10
|
+
};
|
|
11
|
+
export type TmuxSessionConfig = {
|
|
12
|
+
/** Prepended to the worktree hash to form the tmux session name. */
|
|
13
|
+
sessionPrefix: string;
|
|
14
|
+
/** Session option (without the leading `@`) set once every window exists. */
|
|
15
|
+
readyMarker: string;
|
|
16
|
+
/** Variable recorded in the tmux session environment to identify the launcher. */
|
|
17
|
+
launcherPidVar: string;
|
|
18
|
+
env: Record<string, string>;
|
|
19
|
+
windows: TmuxWindowConfig[];
|
|
20
|
+
/** Lines printed before a fresh session starts. */
|
|
21
|
+
summary: string[];
|
|
22
|
+
};
|
|
23
|
+
export declare function parseTmuxConfig(value: unknown): TmuxSessionConfig;
|
|
24
|
+
export declare function loadTmuxConfig(path: string): TmuxSessionConfig;
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
3
|
+
const TMUX_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
|
|
4
|
+
// A purely numeric window name would be read by tmux as an index.
|
|
5
|
+
const WINDOW_NAME = /^(?![0-9]+$)[A-Za-z0-9][A-Za-z0-9_.-]*$/;
|
|
6
|
+
const OPTION_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
|
|
7
|
+
function isRecord(value) {
|
|
8
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
9
|
+
}
|
|
10
|
+
function text(value, label, pattern) {
|
|
11
|
+
if (typeof value !== 'string' ||
|
|
12
|
+
value === '' ||
|
|
13
|
+
(pattern !== undefined && !pattern.test(value))) {
|
|
14
|
+
throw new Error(`tmux config: ${label} must be a ${pattern ? 'valid ' : 'non-empty '}string`);
|
|
15
|
+
}
|
|
16
|
+
return value;
|
|
17
|
+
}
|
|
18
|
+
function envMap(value, label) {
|
|
19
|
+
if (value === undefined)
|
|
20
|
+
return {};
|
|
21
|
+
if (!isRecord(value))
|
|
22
|
+
throw new Error(`tmux config: ${label} must be an object`);
|
|
23
|
+
const result = {};
|
|
24
|
+
for (const [key, raw] of Object.entries(value)) {
|
|
25
|
+
if (!ENV_KEY.test(key))
|
|
26
|
+
throw new Error(`tmux config: ${label} has invalid name "${key}"`);
|
|
27
|
+
if (typeof raw !== 'string' && typeof raw !== 'number') {
|
|
28
|
+
throw new Error(`tmux config: ${label}.${key} must be a string or number`);
|
|
29
|
+
}
|
|
30
|
+
result[key] = String(raw);
|
|
31
|
+
}
|
|
32
|
+
return result;
|
|
33
|
+
}
|
|
34
|
+
function windowConfig(value, index) {
|
|
35
|
+
const label = `windows[${index}]`;
|
|
36
|
+
if (!isRecord(value))
|
|
37
|
+
throw new Error(`tmux config: ${label} must be an object`);
|
|
38
|
+
const cwd = value.cwd === undefined ? undefined : text(value.cwd, `${label}.cwd`);
|
|
39
|
+
if (value.keepOpen !== undefined && typeof value.keepOpen !== 'boolean') {
|
|
40
|
+
throw new Error(`tmux config: ${label}.keepOpen must be a boolean`);
|
|
41
|
+
}
|
|
42
|
+
return {
|
|
43
|
+
name: text(value.name, `${label}.name`, WINDOW_NAME),
|
|
44
|
+
command: text(value.command, `${label}.command`),
|
|
45
|
+
...(cwd === undefined ? {} : { cwd }),
|
|
46
|
+
env: envMap(value.env, `${label}.env`),
|
|
47
|
+
keepOpen: value.keepOpen ?? true,
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
export function parseTmuxConfig(value) {
|
|
51
|
+
if (!isRecord(value))
|
|
52
|
+
throw new Error('tmux config: expected a JSON object');
|
|
53
|
+
if (!Array.isArray(value.windows) || value.windows.length === 0) {
|
|
54
|
+
throw new Error('tmux config: windows must be a non-empty array');
|
|
55
|
+
}
|
|
56
|
+
const windows = value.windows.map(windowConfig);
|
|
57
|
+
const names = new Set(windows.map((window) => window.name));
|
|
58
|
+
if (names.size !== windows.length)
|
|
59
|
+
throw new Error('tmux config: window names must be unique');
|
|
60
|
+
const summary = value.summary ?? [];
|
|
61
|
+
if (!Array.isArray(summary) || summary.some((line) => typeof line !== 'string')) {
|
|
62
|
+
throw new Error('tmux config: summary must be an array of strings');
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
sessionPrefix: text(value.sessionPrefix ?? 'dev-', 'sessionPrefix', TMUX_NAME),
|
|
66
|
+
readyMarker: text(value.readyMarker ?? 'ready', 'readyMarker', OPTION_NAME),
|
|
67
|
+
launcherPidVar: text(value.launcherPidVar ?? 'TMUX_LAUNCHER_PID', 'launcherPidVar', ENV_KEY),
|
|
68
|
+
env: envMap(value.env, 'env'),
|
|
69
|
+
windows,
|
|
70
|
+
summary: summary,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
export function loadTmuxConfig(path) {
|
|
74
|
+
let raw;
|
|
75
|
+
try {
|
|
76
|
+
raw = readFileSync(path, 'utf8');
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
throw new Error(`tmux config: cannot read ${path}: ${error.message}`, {
|
|
80
|
+
cause: error,
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
try {
|
|
84
|
+
return parseTmuxConfig(JSON.parse(raw));
|
|
85
|
+
}
|
|
86
|
+
catch (error) {
|
|
87
|
+
if (error instanceof SyntaxError)
|
|
88
|
+
throw new Error(`tmux config: ${path} is not valid JSON`);
|
|
89
|
+
throw error;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { TmuxSessionConfig } from './config.mts';
|
|
2
|
+
import type { TmuxRun } from './runner.mts';
|
|
3
|
+
import type { SessionContext } from './windows.mts';
|
|
4
|
+
export type FakeTmuxOptions = {
|
|
5
|
+
exists?: boolean;
|
|
6
|
+
windows?: string[];
|
|
7
|
+
dead?: string[];
|
|
8
|
+
/** Polls of the ready option that report not-ready before it becomes `1`. */
|
|
9
|
+
readyAfter?: number;
|
|
10
|
+
/** Never ready. */
|
|
11
|
+
neverReady?: boolean;
|
|
12
|
+
/** The session vanishes after this many has-session calls. */
|
|
13
|
+
vanishAfterChecks?: number;
|
|
14
|
+
/** Subcommands (first argument) that exit 1. */
|
|
15
|
+
failOn?: string[];
|
|
16
|
+
/** Subcommand to fail only the first time it runs. */
|
|
17
|
+
failOnce?: string;
|
|
18
|
+
/** Environment value returned for the launcher pid variable. */
|
|
19
|
+
launcherPid?: string;
|
|
20
|
+
attachStatus?: number | null;
|
|
21
|
+
/** Whether `isPidAlive` reports the recorded launcher as running. Default true. */
|
|
22
|
+
ownerAlive?: boolean;
|
|
23
|
+
};
|
|
24
|
+
export declare function createFakeTmux(options?: FakeTmuxOptions): {
|
|
25
|
+
run: TmuxRun;
|
|
26
|
+
calls: string[][];
|
|
27
|
+
out: string[];
|
|
28
|
+
err: string[];
|
|
29
|
+
sleeps: number[];
|
|
30
|
+
state: {
|
|
31
|
+
exists: boolean;
|
|
32
|
+
windows: string[];
|
|
33
|
+
polls: number;
|
|
34
|
+
checks: number;
|
|
35
|
+
failedOnce: boolean;
|
|
36
|
+
};
|
|
37
|
+
context: (config?: TmuxSessionConfig) => SessionContext;
|
|
38
|
+
launch: (noAttach?: boolean) => {
|
|
39
|
+
noAttach: boolean;
|
|
40
|
+
pid: number;
|
|
41
|
+
sleep: (ms: number) => undefined;
|
|
42
|
+
isPidAlive: () => boolean;
|
|
43
|
+
};
|
|
44
|
+
};
|
|
45
|
+
/** Subcommand lines, e.g. `new-window -t =dev-dabc -n web ...`. */
|
|
46
|
+
export declare function lines(calls: readonly string[][]): string[];
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
const sampleConfig = {
|
|
2
|
+
sessionPrefix: 'dev-',
|
|
3
|
+
readyMarker: 'ready',
|
|
4
|
+
launcherPidVar: 'TMUX_LAUNCHER_PID',
|
|
5
|
+
env: { SHARED: '1' },
|
|
6
|
+
summary: ['Web: http://localhost:3000'],
|
|
7
|
+
windows: [
|
|
8
|
+
{ name: 'web', command: 'serve web', cwd: 'web', env: { SERVICE: 'web' }, keepOpen: true },
|
|
9
|
+
{ name: 'api', command: 'serve api', env: {}, keepOpen: false },
|
|
10
|
+
{ name: 'jobs', command: 'serve jobs', env: {}, keepOpen: true },
|
|
11
|
+
],
|
|
12
|
+
};
|
|
13
|
+
export function createFakeTmux(options = {}) {
|
|
14
|
+
const state = {
|
|
15
|
+
exists: options.exists ?? false,
|
|
16
|
+
windows: [...(options.windows ?? [])],
|
|
17
|
+
polls: 0,
|
|
18
|
+
checks: 0,
|
|
19
|
+
failedOnce: false,
|
|
20
|
+
};
|
|
21
|
+
const calls = [];
|
|
22
|
+
const pids = new Map();
|
|
23
|
+
const deadPids = new Set();
|
|
24
|
+
const pidFor = (name) => {
|
|
25
|
+
if (!pids.has(name)) {
|
|
26
|
+
pids.set(name, String(1000 + pids.size));
|
|
27
|
+
if (options.dead?.includes(name))
|
|
28
|
+
deadPids.add(pids.get(name));
|
|
29
|
+
}
|
|
30
|
+
return pids.get(name);
|
|
31
|
+
};
|
|
32
|
+
const ok = (stdout = '') => ({ status: 0, stdout });
|
|
33
|
+
const fail = { status: 1, stdout: '' };
|
|
34
|
+
const run = (args) => {
|
|
35
|
+
calls.push([...args]);
|
|
36
|
+
const [command = '', ...rest] = args;
|
|
37
|
+
if (options.failOn?.includes(command))
|
|
38
|
+
return fail;
|
|
39
|
+
if (options.failOnce === command && !state.failedOnce) {
|
|
40
|
+
state.failedOnce = true;
|
|
41
|
+
return fail;
|
|
42
|
+
}
|
|
43
|
+
switch (command) {
|
|
44
|
+
case '-V':
|
|
45
|
+
return ok('tmux 3.5\n');
|
|
46
|
+
case 'has-session':
|
|
47
|
+
state.checks += 1;
|
|
48
|
+
if (options.vanishAfterChecks !== undefined && state.checks > options.vanishAfterChecks) {
|
|
49
|
+
state.exists = false;
|
|
50
|
+
}
|
|
51
|
+
return state.exists ? ok() : fail;
|
|
52
|
+
case 'show-options': {
|
|
53
|
+
state.polls += 1;
|
|
54
|
+
const ready = !options.neverReady && state.polls > (options.readyAfter ?? 0);
|
|
55
|
+
return ok(ready ? '1\n' : '');
|
|
56
|
+
}
|
|
57
|
+
case 'show-environment':
|
|
58
|
+
return ok(`${rest[2]}=${options.launcherPid ?? ''}\n`);
|
|
59
|
+
case 'list-windows':
|
|
60
|
+
return ok(state.windows.join('\n'));
|
|
61
|
+
case 'list-panes': {
|
|
62
|
+
const name = rest[1].split(':')[1];
|
|
63
|
+
return ok(`${pidFor(name)}\nnot-a-pid\n`);
|
|
64
|
+
}
|
|
65
|
+
case 'new-session':
|
|
66
|
+
state.exists = true;
|
|
67
|
+
state.windows.push(rest[rest.indexOf('-n') + 1]);
|
|
68
|
+
return ok();
|
|
69
|
+
case 'new-window':
|
|
70
|
+
state.windows.push(rest[rest.indexOf('-n') + 1]);
|
|
71
|
+
return ok();
|
|
72
|
+
case 'kill-session':
|
|
73
|
+
state.exists = false;
|
|
74
|
+
return ok();
|
|
75
|
+
case 'attach':
|
|
76
|
+
return { status: options.attachStatus === undefined ? 0 : options.attachStatus, stdout: '' };
|
|
77
|
+
default:
|
|
78
|
+
return ok();
|
|
79
|
+
}
|
|
80
|
+
};
|
|
81
|
+
const out = [];
|
|
82
|
+
const err = [];
|
|
83
|
+
const sleeps = [];
|
|
84
|
+
const context = (config = sampleConfig) => ({
|
|
85
|
+
config,
|
|
86
|
+
root: '/work',
|
|
87
|
+
session: 'dev-dabc',
|
|
88
|
+
extraEnv: { TMUX_LOG_LEVEL: 'error' },
|
|
89
|
+
tmux: run,
|
|
90
|
+
hasChildren: (pid) => !deadPids.has(pid),
|
|
91
|
+
out: (text) => void out.push(text),
|
|
92
|
+
err: (text) => void err.push(text),
|
|
93
|
+
});
|
|
94
|
+
const launch = (noAttach = true) => ({
|
|
95
|
+
noAttach,
|
|
96
|
+
pid: 4242,
|
|
97
|
+
sleep: (ms) => void sleeps.push(ms),
|
|
98
|
+
isPidAlive: () => options.ownerAlive ?? true,
|
|
99
|
+
});
|
|
100
|
+
return { run, calls, out, err, sleeps, state, context, launch };
|
|
101
|
+
}
|
|
102
|
+
/** Subcommand lines, e.g. `new-window -t =dev-dabc -n web ...`. */
|
|
103
|
+
export function lines(calls) {
|
|
104
|
+
return calls.map((call) => call.join(' '));
|
|
105
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export type HookPayload = Record<string, unknown>;
|
|
2
|
+
/** Tool name across Claude-compatible (`tool_name`), camelCase and bare (`name`) payloads. */
|
|
3
|
+
export declare function hookToolName(payload: HookPayload): string;
|
|
4
|
+
/** The shell command a tool call ran, or '' when the payload carries none. */
|
|
5
|
+
export declare function extractToolCommand(payload: HookPayload): string;
|
|
6
|
+
/** A numeric `exit_code` from the response shapes that carry one; undefined otherwise. */
|
|
7
|
+
export declare function toolExitCode(payload: HookPayload): number | undefined;
|
|
8
|
+
export declare function parseHookPayload(raw: string): HookPayload;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
function isRecord(value) {
|
|
2
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
3
|
+
}
|
|
4
|
+
/** Tool name across Claude-compatible (`tool_name`), camelCase and bare (`name`) payloads. */
|
|
5
|
+
export function hookToolName(payload) {
|
|
6
|
+
for (const key of ['tool_name', 'toolName', 'name']) {
|
|
7
|
+
const value = payload[key];
|
|
8
|
+
if (typeof value === 'string')
|
|
9
|
+
return value;
|
|
10
|
+
}
|
|
11
|
+
return '';
|
|
12
|
+
}
|
|
13
|
+
/** The shell command a tool call ran, or '' when the payload carries none. */
|
|
14
|
+
export function extractToolCommand(payload) {
|
|
15
|
+
for (const key of ['tool_input', 'toolInput', 'input']) {
|
|
16
|
+
const input = payload[key];
|
|
17
|
+
if (isRecord(input) && typeof input.command === 'string')
|
|
18
|
+
return input.command;
|
|
19
|
+
}
|
|
20
|
+
return typeof payload.command === 'string' ? payload.command : '';
|
|
21
|
+
}
|
|
22
|
+
/** A numeric `exit_code` from the response shapes that carry one; undefined otherwise. */
|
|
23
|
+
export function toolExitCode(payload) {
|
|
24
|
+
for (const key of ['tool_response', 'toolResponse', 'toolResult']) {
|
|
25
|
+
const response = payload[key];
|
|
26
|
+
if (isRecord(response) && typeof response.exit_code === 'number')
|
|
27
|
+
return response.exit_code;
|
|
28
|
+
}
|
|
29
|
+
return undefined;
|
|
30
|
+
}
|
|
31
|
+
export function parseHookPayload(raw) {
|
|
32
|
+
try {
|
|
33
|
+
const parsed = JSON.parse(raw);
|
|
34
|
+
return isRecord(parsed) ? parsed : {};
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
return {};
|
|
38
|
+
}
|
|
39
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export { runTmuxCommand, TMUX_USAGE, type TmuxCliDeps } from './cli.mts';
|
|
2
|
+
export { loadTmuxConfig, parseTmuxConfig } from './config.mts';
|
|
3
|
+
export type { TmuxSessionConfig, TmuxWindowConfig } from './config.mts';
|
|
4
|
+
export { launchSession, type LaunchOptions } from './launcher.mts';
|
|
5
|
+
export { createTmuxRun, type TmuxResult, type TmuxRun } from './runner.mts';
|
|
6
|
+
export { renderPostToolReminder, type PostToolTmuxOptions } from './reminder-post-tool.mts';
|
|
7
|
+
export { tmuxSessionName } from './session-name.mts';
|
|
8
|
+
export { quoteShellArg, windowCommand } from './shell-quote.mts';
|
|
9
|
+
export type { SessionContext } from './windows.mts';
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { runTmuxCommand, TMUX_USAGE } from "./cli.mjs";
|
|
2
|
+
export { loadTmuxConfig, parseTmuxConfig } from "./config.mjs";
|
|
3
|
+
export { launchSession } from "./launcher.mjs";
|
|
4
|
+
export { createTmuxRun } from "./runner.mjs";
|
|
5
|
+
export { renderPostToolReminder } from "./reminder-post-tool.mjs";
|
|
6
|
+
export { tmuxSessionName } from "./session-name.mjs";
|
|
7
|
+
export { quoteShellArg, windowCommand } from "./shell-quote.mjs";
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type SessionContext } from './windows.mts';
|
|
2
|
+
export type LaunchOptions = {
|
|
3
|
+
noAttach: boolean;
|
|
4
|
+
/** Pid recorded in the session environment to prove this launcher owns it. */
|
|
5
|
+
pid: number;
|
|
6
|
+
sleep: (milliseconds: number) => void;
|
|
7
|
+
/** Whether the launcher process recorded in the session environment still runs. */
|
|
8
|
+
isPidAlive: (pid: number) => boolean;
|
|
9
|
+
};
|
|
10
|
+
/** Start the configured windows in a worktree-scoped tmux session, or reuse a running one. */
|
|
11
|
+
export declare function launchSession(context: SessionContext, options: LaunchOptions): number;
|