mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-16 03:09:33 +01:00
Every keyboard open and close resized the PTY, and Claude Code's inline renderer answers each height change by clearing the screen and reprinting only the transcript tail that fits, so rows above that tail were lost from tmux for good. Measured on Claude Code 2.1.306 with tmux 3.2a: five keyboard cycles (62x38 to 62x15 and back) left 75 of 100 numbered lines in the pane's history; with the rows held the PTY stays 62x38, no SIGWINCH reaches the pane and all 100 remain (#672). While the keyboard is up the rows captured at the show transition are held through getTerminalDimensions, columns still follow the box, and the screen, now taller than its box, is translated up by --kb-clip so the last content row sits at the bottom of the visible area. This is the one documented exception to the columns-only geometry rule: there the extra rows came from another device and nothing kept the composer in view, here they are this device's own rows held on purpose and the clip keeps the composer visible. The local-echo overlay's setRowLimit narrows the renderer's existing totalRows bound, so one place decides where a long draft stops growing downward. Only inline renderers hold, through a new registry capability keyboardHold: 'inline' (Claude alone) published to the page as window.__codemanKeyboardHoldModes. Full-height layouts such as codex, Claude's fullscreen mode (mouse tracking on, unmeasured), and remote or docker panes resize as before. The hold is released on keyboard close, a shape change, a tab switch, a session update, a reconnect, or the setting turned off. Per-device setting Keep Size Under Keyboard, default on.
717 lines
31 KiB
TypeScript
717 lines
31 KiB
TypeScript
/**
|
|
* @fileoverview Zod validation for CLI registry entries.
|
|
*
|
|
* Every object here is `.strict()`: an unknown key is a hard validation error, not a
|
|
* silently-ignored one. That matters for a security-relevant schema — a typo in a field name
|
|
* must never degrade to "field absent, so the permissive default applies".
|
|
*
|
|
* The load-bearing rule enforced here is `SHELL_TOKEN`: it is what makes it impossible for a
|
|
* `clis.json` entry to smuggle shell metacharacters into the eventual `bash -c "..."` string
|
|
* (see argv.ts's file header for the full model).
|
|
*
|
|
* @module config/cli-registry/schema
|
|
*/
|
|
|
|
import { z } from 'zod';
|
|
import { compileVersionRegex, countCaptureGroups, TOKEN_PATTERNS } from './patterns.js';
|
|
import { isKnownLauncherProfile, isKnownSetenvProfile } from './profiles.js';
|
|
import type { AgentSkillDir, LaunchDefaultSettingKey, McpConfigFormat, ModelConfigResolverName } from './types.js';
|
|
|
|
/** `capabilities.agentSkillDir`: every value must stay a fixed, relative, `..`-free path. */
|
|
export const AGENT_SKILL_DIRS = ['.claude/skills', '.agents/skills'] as const satisfies readonly AgentSkillDir[];
|
|
|
|
/** A bare CLI id: lowercase, starts with a letter, at most 24 chars. Also used as a CSS/URL token. */
|
|
const cliId = z
|
|
.string()
|
|
.regex(/^[a-z][a-z0-9-]{0,23}$/, 'id must be lowercase, start with a letter, and be at most 24 chars');
|
|
|
|
/** An env var name. */
|
|
const envName = z
|
|
.string()
|
|
.regex(/^[A-Z_][A-Z0-9_]*$/, 'env var name must be UPPER_SNAKE_CASE')
|
|
.max(64);
|
|
|
|
/** A relative file path with no traversal or odd characters (MCP sync writes to it). */
|
|
const mcpRelativePath = z
|
|
.string()
|
|
.min(1)
|
|
.max(100)
|
|
.regex(/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/)
|
|
.refine((v) => !v.split('/').includes('..'), 'must not contain ..');
|
|
|
|
/**
|
|
* A shell-safe bare word: no space, quote, backtick, `$`, `;`, `&`, `|`, `<`, `>`, parens,
|
|
* braces, newline or backslash. Every LITERAL in the launch spec (base command, flag names,
|
|
* fixed values) must satisfy this — see argv.ts's file header.
|
|
*/
|
|
const shellToken = z
|
|
.string()
|
|
.min(1)
|
|
.max(256)
|
|
.regex(/^[A-Za-z0-9._:@=+/,-]+$/, 'must be a plain word with no shell metacharacters');
|
|
|
|
const flagToken = z.string().regex(/^--?[A-Za-z0-9][A-Za-z0-9-]*$/, 'must look like -x or --long-flag');
|
|
|
|
const quoteStyle = z.enum(['auto', 'bare', 'double', 'single']);
|
|
|
|
const condSchema: z.ZodType<import('./types.js').Cond> = z.lazy(() =>
|
|
z.union([
|
|
z.object({ param: z.string(), is: z.union([z.string(), z.boolean()]) }).strict(),
|
|
z.object({ param: z.string(), state: z.enum(['set', 'unset']) }).strict(),
|
|
z.object({ allOf: z.array(condSchema).min(1).max(8) }).strict(),
|
|
z.object({ anyOf: z.array(condSchema).min(1).max(8) }).strict(),
|
|
z.object({ not: condSchema }).strict(),
|
|
z.object({ capabilityGate: z.string() }).strict(),
|
|
])
|
|
);
|
|
|
|
const paramSpecSchema = z.union([
|
|
z
|
|
.object({ type: z.literal('enum'), values: z.array(z.string()).min(1).max(16), default: z.string().optional() })
|
|
.strict(),
|
|
z.object({ type: z.literal('bool') }).strict(),
|
|
z.object({ type: z.literal('token'), pattern: z.enum(TOKEN_PATTERNS as [string, ...string[]]) }).strict(),
|
|
z
|
|
.object({
|
|
type: z.literal('engine'),
|
|
source: z.enum([
|
|
'sessionId',
|
|
'sessionName',
|
|
'muxName',
|
|
'effortLevel',
|
|
'effortSettingsJson',
|
|
'codemanPrefixedSessionId',
|
|
'launcherDefaultTarget',
|
|
]),
|
|
})
|
|
.strict(),
|
|
]);
|
|
|
|
const argSpecSchema = z.union([
|
|
z.object({ lit: shellToken, when: condSchema.optional() }).strict(),
|
|
z.object({ flag: flagToken, when: condSchema.optional() }).strict(),
|
|
z.object({ flag: flagToken, value: shellToken, quote: quoteStyle.optional(), when: condSchema.optional() }).strict(),
|
|
z
|
|
.object({ flag: flagToken, valueFrom: z.string(), quote: quoteStyle.optional(), when: condSchema.optional() })
|
|
.strict(),
|
|
z.object({ valueFrom: z.string(), quote: quoteStyle.optional(), when: condSchema.optional() }).strict(),
|
|
]);
|
|
|
|
const variantSchema = z
|
|
.object({
|
|
id: z.string().min(1).max(40),
|
|
when: condSchema.optional(),
|
|
// min(0): the `shell` entry declares a variant with no args — tmux-manager resolves the
|
|
// real login shell in code, since it varies per remote user's /etc/passwd entry.
|
|
args: z.array(argSpecSchema).max(32),
|
|
})
|
|
.strict();
|
|
|
|
const launchSchema = z
|
|
.object({
|
|
params: z.record(z.string(), paramSpecSchema),
|
|
chain: z.enum(['first', 'fallback']).optional(),
|
|
variants: z.array(variantSchema).min(1).max(4),
|
|
legacyConfigAliases: z.record(z.string(), z.string()).optional(),
|
|
legacyConfigField: z.string().min(1).max(40).optional(),
|
|
resumeAppend: z
|
|
.union([
|
|
z.object({ style: z.literal('flag'), flag: flagToken }).strict(),
|
|
z.object({ style: z.literal('positional'), token: shellToken }).strict(),
|
|
])
|
|
.optional(),
|
|
})
|
|
.strict()
|
|
.superRefine((launch, ctx) => {
|
|
const paramNames = new Set(Object.keys(launch.params));
|
|
const checkValueFrom = (name: string, path: (string | number)[]) => {
|
|
if (!paramNames.has(name)) {
|
|
ctx.addIssue({ code: 'custom', message: `valueFrom "${name}" is not a declared param`, path });
|
|
}
|
|
};
|
|
launch.variants.forEach((variant, vi) => {
|
|
variant.args.forEach((arg, ai) => {
|
|
if ('valueFrom' in arg) checkValueFrom(arg.valueFrom, ['variants', vi, 'args', ai, 'valueFrom']);
|
|
});
|
|
});
|
|
if (launch.chain === 'fallback') {
|
|
const last = launch.variants.at(-1);
|
|
if (last?.when) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: 'the last variant of a fallback chain must have no `when` (it must be the guaranteed terminal case)',
|
|
path: ['variants', launch.variants.length - 1, 'when'],
|
|
});
|
|
}
|
|
}
|
|
if (launch.legacyConfigAliases) {
|
|
for (const paramName of Object.keys(launch.legacyConfigAliases)) {
|
|
if (!paramNames.has(paramName)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `legacyConfigAliases key "${paramName}" is not a declared param`,
|
|
path: ['legacyConfigAliases', paramName],
|
|
});
|
|
}
|
|
}
|
|
}
|
|
});
|
|
|
|
const versionProbeSchema = z
|
|
.object({
|
|
arg: shellToken,
|
|
regex: z.string().max(200).optional(),
|
|
requireVersionMatch: z.boolean().optional(),
|
|
retryOnTransientFailure: z.boolean().optional(),
|
|
})
|
|
.strict();
|
|
|
|
const identityProbeSchema = z
|
|
.object({
|
|
arg: shellToken,
|
|
// Same 200-char cap as version.regex, and compiled through the same compileVersionRegex()
|
|
// guard at use time. This is the second and last config-supplied regex in the registry.
|
|
regex: z.string().min(1).max(200),
|
|
})
|
|
.strict();
|
|
|
|
const discoverySchema = z
|
|
.object({
|
|
// min(0): the `shell` entry has no binary of its own (it resolves the login shell in code).
|
|
binaries: z.array(shellToken).max(4),
|
|
searchDirs: z.array(z.string().max(300)).max(16),
|
|
version: versionProbeSchema.optional(),
|
|
identity: identityProbeSchema.optional(),
|
|
launcherProfile: z.string().max(40).optional(),
|
|
launcherTargetParam: z.string().max(40).optional(),
|
|
install: z
|
|
.object({
|
|
// z.record with an enum key type requires every enum member in Zod v4; the install
|
|
// command legitimately varies by platform and most entries only need one or two, so
|
|
// this is a plain object of optional platform keys instead.
|
|
command: z
|
|
.object({
|
|
linux: z.string().max(500).optional(),
|
|
darwin: z.string().max(500).optional(),
|
|
wsl: z.string().max(500).optional(),
|
|
win32: z.string().max(500).optional(),
|
|
})
|
|
.strict(),
|
|
npmPackage: z.string().max(200).optional(),
|
|
docsUrl: z.url().optional(),
|
|
// Requires a `reason` on purpose — see the field's own doc comment in types.ts. A
|
|
// dedicated agent-image layer with no stated reason is a silent id-keyed special case
|
|
// rebuilding itself inside the data this change moved it out of.
|
|
agentImageLayer: z
|
|
.object({ kind: z.literal('dedicated'), reason: z.string().min(1).max(300) })
|
|
.strict()
|
|
.optional(),
|
|
})
|
|
.strict(),
|
|
})
|
|
.strict();
|
|
|
|
const envExportSchema = z
|
|
.object({
|
|
name: envName,
|
|
value: z.union([
|
|
shellToken,
|
|
z
|
|
.object({
|
|
engine: z.enum([
|
|
'sessionId',
|
|
'sessionName',
|
|
'muxName',
|
|
'effortLevel',
|
|
'effortSettingsJson',
|
|
'codemanPrefixedSessionId',
|
|
'launcherDefaultTarget',
|
|
]),
|
|
})
|
|
.strict(),
|
|
]),
|
|
when: condSchema.optional(),
|
|
})
|
|
.strict();
|
|
|
|
const envSchema = z
|
|
.object({
|
|
exports: z.array(envExportSchema).max(16),
|
|
unset: z.array(envName).max(16),
|
|
tmuxSetenvKeys: z.array(envName).max(32),
|
|
dockerExecEnvNames: z.array(envName).max(32),
|
|
configSetenv: z
|
|
.array(z.object({ name: envName, fromParam: z.string().min(1).max(40) }).strict())
|
|
.max(8)
|
|
.optional(),
|
|
allowedPrefixes: z
|
|
.array(
|
|
z
|
|
.string()
|
|
.min(3)
|
|
.max(32)
|
|
.regex(/^[A-Z][A-Z0-9_]*_$/)
|
|
)
|
|
.max(8),
|
|
allowedKeys: z.array(envName).max(8),
|
|
configContentVar: envName.optional(),
|
|
setenvProfile: z.string().max(40).optional(),
|
|
})
|
|
.strict();
|
|
|
|
const echoSchema = z
|
|
.object({
|
|
policy: z.enum(['buffer', 'predict', 'off']),
|
|
anchor: z.union([
|
|
z
|
|
.object({ kind: z.literal('glyph'), glyph: z.string().min(1).max(4), offset: z.number().int().min(0).max(16) })
|
|
.strict(),
|
|
z.object({ kind: z.literal('cursor') }).strict(),
|
|
z.object({ kind: z.literal('none') }).strict(),
|
|
]),
|
|
predictProfile: z.string().max(40).optional(),
|
|
})
|
|
.strict();
|
|
|
|
/**
|
|
* `capabilities.customModelInjection.launchModel`: the `model` launch-param value that
|
|
* selects the injected provider, with `{modelId}` standing for the chosen id. Bounded to
|
|
* the characters the `model`/`model-pi` token patterns accept plus the placeholder braces,
|
|
* so a template can never smuggle a token the argv engine would have to quote.
|
|
*/
|
|
const launchModelTemplate = z
|
|
.string()
|
|
.min(1)
|
|
.max(120)
|
|
.regex(/^[a-zA-Z0-9._\-/:{}]+$/)
|
|
.optional();
|
|
|
|
const capabilitiesSchema = z
|
|
.object({
|
|
external: z.boolean(),
|
|
requiresMux: z.boolean(),
|
|
hooks: z.enum(['none', 'always', 'supervised']),
|
|
transcript: z.enum(['claude-jsonl', 'codex-rollout', 'deepseek-zstd', 'omp-jsonl', 'none']),
|
|
altScreen: z.enum(['strip-full', 'strip-mux-only', 'strip-mux-and-mouse', 'preserve']),
|
|
echo: echoSchema,
|
|
wheelForward: z
|
|
.object({ mode: z.enum(['never', 'version-gated', 'always']), minVersion: z.string().max(20).optional() })
|
|
.strict(),
|
|
// Whether a hollow pane's wheel/touch scroll may be turned into PageUp/PageDown for
|
|
// the CLI to page its own transcript. Distinct from wheelForward (SGR reports).
|
|
// Optional: absent means no paging, the safe default for an unmeasured CLI.
|
|
transcriptPageKeys: z.boolean().optional(),
|
|
// Keep the PTY's rows while a phone keyboard is up (inline renderers only).
|
|
// Optional: absent means the keyboard resizes, the safe default.
|
|
keyboardHold: z.literal('inline').optional(),
|
|
keyboardAccessory: z.enum(['agent', 'shell']),
|
|
privilegedCommandGate: z.boolean(),
|
|
startMode: z.enum(['interactive', 'shell']),
|
|
stripInkBloat: z.boolean(),
|
|
ralph: z.boolean(),
|
|
respawn: z.boolean(),
|
|
effort: z.boolean(),
|
|
agentSkillInjection: z.boolean(),
|
|
// A closed list on purpose: it decides where the server WRITES, and this file is
|
|
// user-editable, so it can never be a free path (`..`, absolute).
|
|
agentSkillDir: z.enum(AGENT_SKILL_DIRS).optional(),
|
|
statusLineTelemetry: z.boolean(),
|
|
// How many columns this CLI indents its transcript body by, so a copy can take
|
|
// that much off the clipboard. Bounded, because it is the whole strip: a copy
|
|
// never removes more than this, nor more than every selected line shares.
|
|
//
|
|
// ⚠ DECLARED, not measured off the pane, and two measured attempts are why.
|
|
// Asking whether the pane painted spaces across the unused part of each row
|
|
// separates a TUI from a shell perfectly where it fires and never
|
|
// over-stripped, but it is a function of pane WIDTH: that padding exists
|
|
// only while a rendered line stops short of the CLI's own layout width, and
|
|
// Claude Code's prose wraps to fill it — the share of padded rows on one
|
|
// live transcript ran 44%, 6%, 6%, 7% and 87% at 123, 160, 198, 235 and 298
|
|
// columns, so the strip did nothing at any ordinary size. Taking the
|
|
// narrowest indent on screen instead fires everywhere and over-strips, since
|
|
// a file listing inside the transcript can be the narrowest thing on it.
|
|
// A declared width cannot do either. Absent means no strip, so a CLI whose
|
|
// transcript layout nobody has measured is never touched.
|
|
transcriptGutter: z.number().int().min(1).max(8).optional(),
|
|
// Literal text matched by a `wait-output` long-poll, never compiled as a regex.
|
|
composerReadyMark: z.string().min(1).max(64).optional(),
|
|
workDetect: z
|
|
.object({
|
|
promptGlyph: z.string().min(1).max(8),
|
|
// Config-supplied regex, so it goes through the same guard as `version.regex`:
|
|
// ~/.codeman/clis.json can set this, and the compiled pattern runs on the PTY
|
|
// hot path, where a nested quantifier would be a ReDoS against the event loop.
|
|
// A broken pattern must also fail at LOAD time rather than inside a data handler.
|
|
workingLine: z
|
|
.string()
|
|
.min(1)
|
|
.refine(
|
|
(src) => compileVersionRegex(src) !== null,
|
|
'workingLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
|
|
),
|
|
// Same guard, same reasons: this one runs over the foot of a pane capture every
|
|
// time a session settles, and ~/.codeman/clis.json can set it.
|
|
watchingLine: z
|
|
.string()
|
|
.min(1)
|
|
.refine(
|
|
(src) => compileVersionRegex(src) !== null,
|
|
'watchingLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
|
|
)
|
|
.optional(),
|
|
// Bounded hard: this is how far up the screen a config file may push the search,
|
|
// and every row it adds is one more row the agent itself may be able to write.
|
|
watchingLines: z.number().int().min(1).max(8).optional(),
|
|
// Same guard again: tested against a pane row every time a session settles.
|
|
awaitingLine: z
|
|
.string()
|
|
.min(1)
|
|
.refine(
|
|
(src) => compileVersionRegex(src) !== null,
|
|
'awaitingLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
|
|
)
|
|
.optional(),
|
|
// Same guard again: run over the foot of a pane capture every time a session
|
|
// settles and on a timer while a dialog is up, and ~/.codeman/clis.json can set it.
|
|
blockedLine: z
|
|
.string()
|
|
.min(1)
|
|
.refine(
|
|
(src) => compileVersionRegex(src) !== null,
|
|
'blockedLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
|
|
)
|
|
.optional(),
|
|
// Wider than `watchingLines` because a dialog's options wrap at narrow widths (codex
|
|
// needs 20 at 36 columns). That is safe only for a pattern that ends on the dialog's
|
|
// own footer: the rows above it, which the agent may write, can then supply a
|
|
// marker but never the footer. Still bounded, since it is also how much text the
|
|
// pattern runs over.
|
|
blockedLines: z.number().int().min(1).max(24).optional(),
|
|
})
|
|
.strict()
|
|
// A window with nothing to search is a typo, not a configuration. Refused at LOAD
|
|
// time for the same reason `privilegedParams[].param` is checked against the params
|
|
// the entry declares: the failure is otherwise silent and looks like a feature that
|
|
// simply never fires.
|
|
.refine(
|
|
(v) => v.watchingLines === undefined || v.watchingLine !== undefined,
|
|
'watchingLines has nothing to bound without a watchingLine'
|
|
)
|
|
.refine(
|
|
(v) => v.blockedLines === undefined || v.blockedLine !== undefined,
|
|
'blockedLines has nothing to bound without a blockedLine'
|
|
)
|
|
.optional(),
|
|
model: z
|
|
.object({ source: z.enum(['flag', 'claude-settings-file', 'none']), param: z.string().optional() })
|
|
.strict(),
|
|
// Same guard as the workDetect patterns: ~/.codeman/clis.json can set it, and it runs
|
|
// over the foot of a pane capture every time a session settles. Exactly one capture
|
|
// group (the model), checked here so a pattern without one fails at LOAD time instead
|
|
// of silently never naming a model.
|
|
modelDetect: z
|
|
.object({
|
|
screenLine: z
|
|
.string()
|
|
.min(1)
|
|
.refine(
|
|
(src) => compileVersionRegex(src) !== null && countCaptureGroups(src) === 1,
|
|
'screenLine must be a regex compileVersionRegex() accepts (at most 200 characters, no nested quantifiers) with exactly one capture group'
|
|
)
|
|
.optional(),
|
|
// Bounded hard, like watchingLines: every row it adds is one more row the agent
|
|
// itself may be able to write. 8 is the reader's own cap (readScreenModel); a
|
|
// window taller than the CLI's footer needs a pattern only that CLI's chrome can
|
|
// satisfy at its position, as opencode's does by taking the LAST composer row.
|
|
screenLines: z.number().int().min(1).max(8).optional(),
|
|
// Single tokens, bounded: each is compared against one captured field.
|
|
rejectWords: z.array(z.string().min(1).max(40).regex(/^\S+$/)).max(32).optional(),
|
|
// A NAMED reader (src/model-config-resolvers.ts), never code in config.
|
|
configResolver: z.enum(['deepseek-route'] as const satisfies readonly ModelConfigResolverName[]).optional(),
|
|
})
|
|
.strict()
|
|
// Typos rather than configurations, refused at LOAD time like watchingLines.
|
|
.refine(
|
|
(v) => v.screenLine !== undefined || v.configResolver !== undefined,
|
|
'modelDetect declares nothing to read'
|
|
)
|
|
.refine(
|
|
(v) => v.screenLines === undefined || v.screenLine !== undefined,
|
|
'screenLines has nothing to bound without a screenLine'
|
|
)
|
|
.refine(
|
|
(v) => v.rejectWords === undefined || v.screenLine !== undefined,
|
|
'rejectWords has nothing to filter without a screenLine'
|
|
)
|
|
.optional(),
|
|
// Launch param -> synced App Settings key. The values are a closed enum, like
|
|
// configResolver: a clis.json override names one of the settings this build knows
|
|
// how to validate, never an arbitrary key. Params are checked against the declared
|
|
// ones in the superRefine below.
|
|
launchDefaults: z
|
|
.record(
|
|
z.string(),
|
|
z.enum(['codexModel', 'codexReasoningEffort'] as const satisfies readonly LaunchDefaultSettingKey[])
|
|
)
|
|
.refine((v) => Object.keys(v).length >= 1 && Object.keys(v).length <= 8, 'launchDefaults takes 1 to 8 params')
|
|
.optional(),
|
|
privilegedParams: z
|
|
.array(
|
|
z
|
|
.object({
|
|
param: z.string(),
|
|
clampTo: z.union([z.boolean(), z.string()]),
|
|
materializeWhenAbsent: z.boolean().optional(),
|
|
})
|
|
.strict()
|
|
)
|
|
.max(8),
|
|
// Exact env var NAMES, not prefixes: this list is a targeted deny, and a prefix here
|
|
// would let one entry silently strip a whole namespace off every owner's overrides. The
|
|
// bound is generous because a longer list only takes more away from non-granted owners:
|
|
// copilot's COPILOT_ prefix covers dozens of variables that run code or redirect its token.
|
|
privilegedEnvKeys: z.array(envName).max(48),
|
|
gates: z.record(z.string(), z.object({ minVersion: z.string().max(20), failClosed: z.boolean() }).strict()),
|
|
maxFrameBytes: z.number().int().positive().optional(),
|
|
newline: z.enum(['line-feed', 'esc-enter']).optional(),
|
|
mcpConfig: z
|
|
.object({
|
|
// Home-relative, no traversal: sync writes to this path.
|
|
path: mcpRelativePath,
|
|
// Home-relative fallback used when `path` is absent. Same no-traversal rule as `path`:
|
|
// sync reads it and, when it parses as plain JSON, writes to it.
|
|
altPath: mcpRelativePath.optional(),
|
|
// Every value must be a known McpConfigFormat (types.ts); mcp-sync.ts's dialect table is
|
|
// keyed by the same type, so an adapter-less format fails to compile there.
|
|
format: z.enum([
|
|
'claude-json',
|
|
'gemini-json',
|
|
'codex-toml',
|
|
'opencode-json',
|
|
'antigravity-json',
|
|
'copilot-json',
|
|
] as const satisfies readonly McpConfigFormat[]),
|
|
// The env var the CLI reads to move the file, and the path under it (same no-traversal
|
|
// rule: sync writes there too). Resolved from the server env at call time, never here.
|
|
relocation: z.object({ envVar: envName, path: mcpRelativePath }).strict().optional(),
|
|
})
|
|
.strict()
|
|
.optional(),
|
|
customModelInjection: z.discriminatedUnion('kind', [
|
|
z
|
|
.object({
|
|
kind: z.literal('env'),
|
|
baseUrlVar: envName,
|
|
apiKeyVar: envName,
|
|
// Empty is valid: deepseek's model routing is a profile-composition concern, not
|
|
// an env var, so it declares baseUrl/apiKey injection with no model var at all.
|
|
modelVars: z.array(envName).max(8),
|
|
launchModel: launchModelTemplate,
|
|
// Optional: the env var to carry a discovered per-model context-window size
|
|
// (claude's CLAUDE_CODE_MAX_CONTEXT_TOKENS), and/or the env var that isolates
|
|
// this session's config/credential directory from the user's real one (claude's
|
|
// CLAUDE_CONFIG_DIR) so an injected API key never collides with a stored OAuth
|
|
// session. See the customModelInjection doc comment in cli-registry/types.ts.
|
|
contextLengthVar: envName.optional(),
|
|
configDirVar: envName.optional(),
|
|
// Relative path, WITHIN the isolated configDirVar directory, of a trust-dialog
|
|
// seed file the CLI itself owns the shape of — claude's `.claude.json`
|
|
// `customApiKeyResponses.approved` list, the same field an interactive "Detected
|
|
// a custom API key — use it?" prompt writes to on a real terminal. Only makes
|
|
// sense alongside configDirVar (an isolated, otherwise-empty directory has none
|
|
// of a real profile's prior approvals), and only implemented for the
|
|
// 'claude-api-key-responses' shape today — see custom-model-injection-apply.ts.
|
|
apiKeyTrustFile: z
|
|
.object({ relPath: z.string().min(1).max(80), shape: z.literal('claude-api-key-responses') })
|
|
.strict()
|
|
.optional(),
|
|
// An isolated config directory replays the CLI's whole first-run sequence (theme
|
|
// picker, security notes, per-project trust dialog, bypass-permissions warning)
|
|
// on every launch, same root cause as apiKeyTrustFile above — this reuses that
|
|
// same file to pre-seed the state a real, already-onboarded profile carries. See
|
|
// the customModelInjection doc comment in cli-registry/types.ts.
|
|
skipFirstRunPrompts: z.boolean().optional(),
|
|
// DeepSeek-only, confirmed by reading its own bundled SDK source: it concatenates
|
|
// "/chat/completions" onto baseUrlVar's value with no "/v1" of its own, while
|
|
// llama-swap/llama.cpp only serves the "/v1/..." path — claude/gemini must NOT
|
|
// get this. See the customModelInjection doc comment in cli-registry/types.ts.
|
|
appendV1Suffix: z.boolean().optional(),
|
|
})
|
|
.strict(),
|
|
z
|
|
.object({
|
|
kind: z.literal('configContentEnv'),
|
|
envVar: envName,
|
|
template: z.literal('opencode-json'),
|
|
launchModel: launchModelTemplate,
|
|
})
|
|
.strict(),
|
|
z
|
|
.object({
|
|
kind: z.literal('configDir'),
|
|
dirEnvVar: envName,
|
|
fileName: z.string().min(1).max(80),
|
|
template: z.enum(['codex-toml', 'pi-models-json', 'omp-models-yml', 'grok-toml']),
|
|
launchModel: launchModelTemplate,
|
|
})
|
|
.strict(),
|
|
z.object({ kind: z.literal('unsupported') }).strict(),
|
|
]),
|
|
})
|
|
.strict();
|
|
|
|
const credStoreSchema = z
|
|
.object({
|
|
rel: z.string().min(1).max(100),
|
|
shareDirs: z.array(z.string().max(100)).optional(),
|
|
shareFiles: z.array(z.string().max(100)).optional(),
|
|
seedFiles: z.array(z.string().max(100)).optional(),
|
|
seedWhole: z.boolean().optional(),
|
|
})
|
|
.strict();
|
|
|
|
/**
|
|
* A remote/docker default pane command: space-separated bare words from the SAME safe
|
|
* charset as `shellToken` (no shell metacharacters), so `claude --dangerously-skip-permissions`
|
|
* is expressible while still excluding `;`, `|`, `$`, backticks and quotes — this is not an
|
|
* escape hatch into arbitrary shell text, it is one bare command plus bare flags.
|
|
*/
|
|
const commandLine = z
|
|
.string()
|
|
.min(1)
|
|
.max(200)
|
|
.regex(
|
|
/^[A-Za-z0-9._:@=+/,-]+( [A-Za-z0-9._:@=+/,-]+)*$/,
|
|
'must be space-separated bare words with no shell metacharacters'
|
|
);
|
|
|
|
const overlayTargetSchema = z.union([
|
|
z.object({ command: commandLine.optional(), rootCommand: commandLine.optional() }).strict(),
|
|
z.object({ disabled: z.literal(true) }).strict(),
|
|
]);
|
|
|
|
const overlaysSchema = z
|
|
.object({
|
|
remote: overlayTargetSchema.optional(),
|
|
docker: overlayTargetSchema.optional(),
|
|
credStore: credStoreSchema.optional(),
|
|
})
|
|
.strict();
|
|
|
|
export const CliEntrySchema = z
|
|
.object({
|
|
id: cliId,
|
|
label: z.string().min(1).max(60),
|
|
shortBadge: z.string().min(1).max(6),
|
|
accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'accent must be a 6-digit hex colour'),
|
|
enabled: z.boolean(),
|
|
stock: z.boolean(),
|
|
order: z.number().int(),
|
|
kind: z.enum(['agent', 'shell']),
|
|
discovery: discoverySchema,
|
|
launch: launchSchema,
|
|
env: envSchema,
|
|
capabilities: capabilitiesSchema,
|
|
overlays: overlaysSchema,
|
|
})
|
|
.strict()
|
|
.superRefine((entry, ctx) => {
|
|
const gateNames = new Set(Object.keys(entry.capabilities.gates));
|
|
const walkConds = (cond: import('./types.js').Cond | undefined) => {
|
|
if (!cond) return;
|
|
if ('capabilityGate' in cond && !gateNames.has(cond.capabilityGate)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `capabilityGate "${cond.capabilityGate}" is not declared in capabilities.gates`,
|
|
});
|
|
}
|
|
if ('allOf' in cond) cond.allOf.forEach(walkConds);
|
|
if ('anyOf' in cond) cond.anyOf.forEach(walkConds);
|
|
if ('not' in cond) walkConds(cond.not);
|
|
};
|
|
for (const variant of entry.launch.variants) {
|
|
walkConds(variant.when);
|
|
for (const arg of variant.args) walkConds(arg.when);
|
|
}
|
|
|
|
// Reject a profile name this build does not implement, rather than letting it fail
|
|
// closed at use time. An unimplemented `launcherProfile` would make the CLI look
|
|
// permanently uninstalled, and an unimplemented `setenvProfile` would silently skip
|
|
// setup the CLI needs; both are far easier to diagnose as a load-time error naming the
|
|
// field. (`echo.predictProfile` is deliberately NOT checked here — see profiles.ts.)
|
|
const { launcherProfile } = entry.discovery;
|
|
if (launcherProfile !== undefined && !isKnownLauncherProfile(launcherProfile)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `discovery.launcherProfile "${launcherProfile}" is not a profile this build implements`,
|
|
path: ['discovery', 'launcherProfile'],
|
|
});
|
|
}
|
|
// An env var exported from a param that does not exist would silently export nothing,
|
|
// and for DSH_PERMISSION_MODE that means silently losing a permission clamp.
|
|
const declaredParams = new Set(Object.keys(entry.launch.params));
|
|
entry.env.configSetenv?.forEach((mapping, i) => {
|
|
if (!declaredParams.has(mapping.fromParam)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `configSetenv fromParam "${mapping.fromParam}" is not a declared launch param`,
|
|
path: ['env', 'configSetenv', i, 'fromParam'],
|
|
});
|
|
}
|
|
});
|
|
|
|
// Same class of silent failure on the OTHER privileged surface, and this one is a
|
|
// security control: `privilegedParams[].param` is the multi-user bypass clamp's only
|
|
// handle on a CLI's privilege switch, and a name that is not a declared param clamps
|
|
// NOTHING — no load error, no failing test, the clamp simply stops running. The clamp
|
|
// resolves the name through `legacyConfigAliases`, so this check is what keeps the two
|
|
// in ONE namespace rather than two that merely coincide today: they do not for codex
|
|
// (`bypassApprovals` vs `dangerouslyBypassApprovals`), and giving deepseek's
|
|
// `permissionMode` an alias later would otherwise have removed its clamp with nothing
|
|
// saying so.
|
|
entry.capabilities.privilegedParams.forEach((clamp, i) => {
|
|
if (!declaredParams.has(clamp.param)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `privilegedParams param "${clamp.param}" is not a declared launch param`,
|
|
path: ['capabilities', 'privilegedParams', i, 'param'],
|
|
});
|
|
}
|
|
});
|
|
|
|
// Same silent-no-op class again: a launch default for a param the entry never declared
|
|
// would be filled into the config object and then read by nothing. And without a
|
|
// `legacyConfigField` the entry's params are read off the request body itself, where a
|
|
// filled `model` would be a different field (claude's per-session one), so refuse it.
|
|
const { launchDefaults } = entry.capabilities;
|
|
if (launchDefaults !== undefined) {
|
|
if (entry.launch.legacyConfigField === undefined) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: 'launchDefaults needs launch.legacyConfigField to fill',
|
|
path: ['capabilities', 'launchDefaults'],
|
|
});
|
|
}
|
|
for (const param of Object.keys(launchDefaults)) {
|
|
if (!declaredParams.has(param)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `launchDefaults param "${param}" is not a declared launch param`,
|
|
path: ['capabilities', 'launchDefaults', param],
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
const { setenvProfile } = entry.env;
|
|
if (setenvProfile !== undefined && !isKnownSetenvProfile(setenvProfile)) {
|
|
ctx.addIssue({
|
|
code: 'custom',
|
|
message: `env.setenvProfile "${setenvProfile}" is not a profile this build implements`,
|
|
path: ['env', 'setenvProfile'],
|
|
});
|
|
}
|
|
});
|
|
|
|
export type ValidatedCliEntry = z.infer<typeof CliEntrySchema>;
|