@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/skills/preprocess.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `!command` body preprocessing.
+ *
+ * Skills may embed shell-command blocks that the SDK runs at body-load
+ * time and splices the output into the rendered body before the model
+ * sees it. The feature is **disabled by default** because the OSS skill
+ * survey (29 real skills, 0 used `!command`) suggests it's a rarely-
+ * needed compatibility shim, not a hot-path tool.
+ *
+ * Two block forms are recognised, mirroring Claude Code's surface:
+ *
+ *   - Inline: a single-backticked command line whose body starts with
+ *     `!`, e.g. `` `!git log --oneline -5` ``.
+ *   - Fenced: a triple-backtick block tagged with `!`, e.g.
+ *     ```` ```!\nbash -c 'pwd'\n``` ````.
+ *
+ * Three modes, gated through {@link SkillsPreprocessingConfig.mode}:
+ *
+ *   - `'disabled'` (default) — every block is left literal. No execution,
+ *     no telemetry. Cheapest path; ships zero attack surface.
+ *   - `'allowlisted'` — every block's first shell-tokenised argv must
+ *     match one of {@link SkillsPreprocessingConfig.allow}. Non-matches
+ *     are replaced with a disable marker + `preprocess_blocked` event.
+ *     Matches execute through the consumer's bash (or powershell, gated
+ *     by env-var).
+ *   - `'full'` — every block executes. Reserved for trusted environments;
+ *     third-party skills always bypass this mode regardless of opt-in.
+ *
+ * Tier gate runs *before* the mode gate: third-party skills never
+ * execute, ever, regardless of `mode`. The trust derivation is the same
+ * value `SkillsManager.isTrusted` returns.
+ *
+ * Substitution order (per `skills-trust.md` §4):
+ *
+ *   1. `${QODO_SKILL_DIR}` substituted in the entire body text before
+ *      block detection. Authors compose commands like
+ *      `` `!cat ${QODO_SKILL_DIR}/references/style.md` `` so the
+ *      command's `cwd` (and any path arguments) resolve correctly even
+ *      when the skill is loaded from a non-default source.
+ *   2. `!command` blocks executed; output spliced in place.
+ *   3. `$ARGUMENTS` substitution (separate path) runs after
+ *      preprocessing — output is treated as inert text, so a command
+ *      whose stdout contains `$ARGUMENTS` will see it substituted on
+ *      the final pass.
+ *
+ * Threat model:
+ *
+ *   - Skill body content is untrusted even from a `trusted` tier — a
+ *     skill author may have copied a recipe from the wider OSS
+ *     ecosystem without realising it embeds a `!command`. The
+ *     allowlist is the only mechanism that can be safely relied on for
+ *     blast-radius control; `full` mode means "I trust every skill in
+ *     this catalog".
+ *   - `!command` blocks run through the consumer's shell, which gives
+ *     them pipes / redirects / shell builtins. The allowlist gates the
+ *     first command name only; downstream pipe tokens are not screened.
+ *     Operators wiring `mode: 'full'` accept that trade-off. The right
+ *     answer is to either disallow shell metacharacters in the command
+ *     line entirely (rejected) or trust the operator's allowlist
+ *     (accepted, with this caveat documented).
+ *   - Hard kill via `setTimeout` + `SIGKILL`. Output capped during
+ *     buffering — a multi-gigabyte stream is truncated as it arrives,
+ *     not after the process completes.
+ *   - `cwd` defaults to the skill's directory; we don't enforce
+ *     containment because the shell can `cd` freely. Operators wiring
+ *     `full` mode accept that.
+ *
+ * The module is async (subprocess spawn) but pure-ish: it takes a body,
+ * returns a transformed body + telemetry events. Caller (typically the
+ * MCP server's `get_skill` handler) forwards the events to the
+ * configured sink.
+ */
+import type { ParsedSkill, SkillEvent, SkillsPreprocessingConfig } from './types.js';
+/**
+ * Environment-variable gate matching Claude Code's
+ * `CLAUDE_CODE_USE_POWERSHELL_TOOL`. When unset, skills declaring
+ * `shell: powershell` get their `!command` blocks blocked with a
+ * `powershell_disabled` event regardless of mode.
+ */
+export declare const POWERSHELL_GATE_ENV_VAR = "QODO_SKILLS_ENABLE_POWERSHELL";
+/**
+ * Inputs to `preprocessBody`. Split into "what was parsed" (`skill`)
+ * and "runtime state" (`isTrusted`, `env`, `now`) so tests can inject
+ * deterministic values.
+ */
+export interface PreprocessContext {
+    readonly skill: ParsedSkill;
+    /** Whether the skill's source is trusted enough to execute commands. */
+    readonly isTrusted: boolean;
+    /**
+     * Process environment readable from inside the spawned commands.
+     * Tests inject; production passes `process.env`.
+     */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /**
+     * High-resolution timer source for `durationMs`. Defaults to
+     * `Date.now()`; tests inject a stub.
+     */
+    readonly now?: () => number;
+}
+export interface PreprocessResult {
+    /** Body with `!command` blocks rendered (executed, blocked, or untouched). */
+    readonly body: string;
+    /** Telemetry events. Caller forwards to the configured sink. */
+    readonly events: readonly SkillEvent[];
+}
+/**
+ * Preprocess a skill body. Returns the transformed body + telemetry.
+ *
+ * Calling with `mode: 'disabled'` is a no-op fast-path: the body is
+ * returned unchanged and no events are emitted. Operators who never
+ * configure preprocessing pay zero overhead.
+ */
+export declare function preprocessBody(rawBody: string, ctx: PreprocessContext, config: SkillsPreprocessingConfig | undefined): Promise<PreprocessResult>;
+interface CommandBlock {
+    /** Whole match (the slice that gets replaced in the body). */
+    readonly raw: string;
+    /** Just the command line, no fence/backtick wrapping. */
+    readonly command: string;
+    /** Byte offset of `raw` within the body, used to apply replacements. */
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Find all `!command` blocks in a body. The scanner walks the body once
+ * and emits matches in source order so the replacement step can stitch
+ * the output back together with a single pass.
+ *
+ * The scanner ignores `!`-prefixed commands inside non-`!` fenced
+ * blocks — those are narrative code samples, not commands. Conversely,
+ * a `!`-tagged fenced block hides any inner backticks from the inline
+ * regex.
+ */
+export declare function findCommandBlocks(body: string): CommandBlock[];
+/**
+ * Replace `${QODO_SKILL_DIR}` (and any future `${QODO_*}` vars) in the
+ * body. The substitution is global — every occurrence is replaced.
+ *
+ * Only `QODO_SKILL_DIR` is supported in this wave; unknown `${QODO_*}`
+ * references pass through literal so a typo doesn't disappear silently.
+ */
+export declare function substituteQodoVars(body: string, skill: ParsedSkill): string;
+/**
+ * Extract the first shell-tokenised argv from a command line. Matches
+ * `cmd args` and `cmd "with spaces"`; returns the bare command name
+ * with no quotes. `null` if the line is empty after tokenisation.
+ *
+ * Deliberately incomplete — we only need to know the first command
+ * name for allowlist gating. Pipes, env assignment, here-docs, and
+ * other shell features fall through to the shell itself (`bash -c`).
+ *
+ * `FOO=bar cmd` is peeled — env-assign prefixes don't change the
+ * command identity for allowlist purposes, and an attacker shouldn't
+ * be able to dodge an allowlist that whitelists `cmd` by prepending
+ * `PATH=/evil cmd`.
+ */
+export declare function parseFirstToken(line: string): string | null;
+/**
+ * Check whether `cmd` matches one of the allowlist entries. Match is
+ * left-anchored:
+ *
+ *   - Bare names (`git`) match the basename of `cmd` (so `git` matches
+ *     both `git` and `/usr/bin/git`).
+ *   - Path-bearing entries (`/usr/bin/jq`, `./bin/foo`) must match
+ *     verbatim.
+ */
+export declare function isAllowlisted(cmd: string, allow: readonly string[]): boolean;
+export {};
+//# sourceMappingURL=preprocess.d.ts.map

package/dist/skills/preprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preprocess.d.ts","sourceRoot":"","sources":["../../src/skills/preprocess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAMH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,kCAAkC,CAAC;AAKvE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;CACxC;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,yBAAyB,GAAG,SAAS,GAC5C,OAAO,CAAC,gBAAgB,CAAC,CA0E3B;AAmBD,UAAU,YAAY;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAiE9D;AAqBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAK3E;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqB3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAS5E"}