@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/skills/sources/walk.js

@@ -0,0 +1,264 @@
+/**
+ * Shared filesystem walker for skill sources.
+ *
+ * Sits below the per-source-type walkers in `./project.ts`, `./user.ts`,
+ * etc. Each `SKILL.md` discovered yields a `WalkedSkill` carrying:
+ *
+ *   - `dirPath` — absolute path to the skill's directory.
+ *   - `skillFilePath` — absolute path to the `SKILL.md`.
+ *   - `mtimeMs` — modification time of `SKILL.md` for slim-index ordering.
+ *
+ * Per `skills-edge-cases.md` §1.9 / §1.10 symlinks are bounded:
+ *
+ *   - Symlink resolution count per skill is capped at `SYMLINK_HOP_CAP`.
+ *   - A symlink resolving outside the skill directory's tree is rejected
+ *     before any read.
+ *
+ * The walker never reads `SKILL.md` body content — it surfaces existence
+ * + mtime only. The parser (`../parser.ts`) handles the actual read.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+/** Per-skill symlink-resolution cap. Mirrors POSIX `O_NOFOLLOW`-style behavior. */
+export const SYMLINK_HOP_CAP = 8;
+/**
+ * Files inside a skill's directory should be one level deep from
+ * `SKILL.md` (per `skills.md` §1.1). The walker enforces nothing about
+ * the body — it just locates `SKILL.md`. Filenames the walker recognizes:
+ *
+ *   - `SKILL.md` (canonical, per the open standard).
+ *   - `skill.md` (lower-case fallback, observed in OSS skills).
+ *
+ * Listed in priority order — the first match wins per directory.
+ */
+const SKILL_FILE_NAMES = ['SKILL.md', 'skill.md'];
+/**
+ * Walk a single directory non-recursively and return every immediate
+ * sub-directory that contains a `SKILL.md` (or `skill.md`) file. The
+ * walker treats each subdirectory as one skill — supporting files
+ * (`reference.md`, `scripts/`, `assets/`) ride along but aren't surfaced
+ * by this walker.
+ *
+ * Errors thrown by the underlying `readdir` are propagated to the caller
+ * so the source-type walker can attach `sdk.skill.error` events with the
+ * source identity.
+ */
+export async function findSkillDirectories(root) {
+    const real = await safeRealPath(root);
+    if (real === null)
+        return [];
+    let entries;
+    try {
+        entries = await fs.readdir(real, { withFileTypes: true });
+    }
+    catch (err) {
+        throw wrapFsError(`readdir failed for ${real}`, err);
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        if (entry.name.startsWith('.'))
+            continue; // skip dotfiles
+        const candidateDir = path.join(real, entry.name);
+        const resolved = await resolveSkillDir(real, candidateDir);
+        if (resolved === null)
+            continue;
+        const skillFile = await findSkillFile(resolved);
+        if (skillFile === null)
+            continue;
+        let stat;
+        try {
+            stat = await fs.stat(skillFile);
+        }
+        catch {
+            continue;
+        }
+        found.push({
+            dirPath: resolved,
+            skillFilePath: skillFile,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+        });
+    }
+    return found;
+}
+/**
+ * Variant for sources whose root layout is "directory contains many
+ * subdirectories AND each subdirectory may itself contain skill
+ * subdirectories" — e.g. a glob expansion like `plugins/*\/skills`. The
+ * walker does NOT recurse arbitrarily deep; it probes exactly one level
+ * down from each immediate child.
+ *
+ * Pragmatically: if `root/foo/SKILL.md` exists, `foo` is a skill;
+ * otherwise the walker checks `root/foo/skills/` (legacy plugin layout).
+ */
+export async function findSkillDirectoriesWithLegacyPluginLayout(root) {
+    const direct = await findSkillDirectories(root);
+    if (direct.length > 0)
+        return direct;
+    // Fallback: check `<root>/<plugin>/skills/`.
+    const real = await safeRealPath(root);
+    if (real === null)
+        return [];
+    let entries;
+    try {
+        entries = await fs.readdir(real, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        if (entry.name.startsWith('.'))
+            continue;
+        const pluginRoot = path.join(real, entry.name, 'skills');
+        try {
+            const child = await findSkillDirectories(pluginRoot);
+            out.push(...child);
+        }
+        catch {
+            // ignore — plugin sub-directory may not have skills
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a candidate skill directory through symlinks while:
+ *   - keeping the resolved path inside `parentRoot` (rejection on escape),
+ *   - bounding the hop count at `SYMLINK_HOP_CAP` (rejection on loop).
+ *
+ * Returns the resolved absolute path on success, `null` on rejection.
+ * The walker uses `null` rather than throwing because a single
+ * malformed skill subdirectory should not poison the entire source —
+ * the manager emits an `sdk.skill.error` event with the offending path
+ * captured elsewhere.
+ */
+async function resolveSkillDir(parentRoot, candidate) {
+    let current = candidate;
+    for (let hop = 0; hop < SYMLINK_HOP_CAP; hop += 1) {
+        let stat;
+        try {
+            stat = await fs.lstat(current);
+        }
+        catch {
+            return null;
+        }
+        if (stat.isDirectory() && !stat.isSymbolicLink()) {
+            // Final canonical path; verify it stays within parentRoot.
+            const canonical = await safeRealPath(current);
+            if (canonical === null)
+                return null;
+            const parentCanonical = await safeRealPath(parentRoot);
+            if (parentCanonical === null)
+                return null;
+            const rel = path.relative(parentCanonical, canonical);
+            if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                // resolves outside the parent root — reject per §1.10
+                return null;
+            }
+            return canonical;
+        }
+        if (stat.isSymbolicLink()) {
+            let target;
+            try {
+                target = await fs.readlink(current);
+            }
+            catch {
+                return null;
+            }
+            const resolvedTarget = path.isAbsolute(target)
+                ? target
+                : path.resolve(path.dirname(current), target);
+            current = resolvedTarget;
+            continue;
+        }
+        return null;
+    }
+    // Exceeded hop cap — loop or pathological depth.
+    return null;
+}
+async function findSkillFile(dir) {
+    for (const name of SKILL_FILE_NAMES) {
+        const candidate = path.join(dir, name);
+        try {
+            const stat = await fs.lstat(candidate);
+            if (stat.isFile())
+                return candidate;
+            if (stat.isSymbolicLink()) {
+                const resolved = await safeRealPath(candidate);
+                if (resolved === null)
+                    continue;
+                const relativeToDir = path.relative(dir, resolved);
+                // SKILL.md must live inside the skill directory — symlink escape rejected.
+                if (relativeToDir.startsWith('..') || path.isAbsolute(relativeToDir)) {
+                    continue;
+                }
+                const realStat = await fs.stat(resolved).catch(() => null);
+                if (realStat !== null && realStat.isFile())
+                    return resolved;
+            }
+        }
+        catch {
+            // not found — try next variant
+        }
+    }
+    return null;
+}
+/**
+ * Walk a path with symlink-resolution and return its canonical absolute
+ * form, or `null` if the path doesn't exist or cannot be canonicalised.
+ */
+export async function safeRealPath(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk upward from `cwd` looking for ancestor directories that contain a
+ * `<segment>` directory (typically `.qodo/skills` for the project source).
+ * Returns the matching ancestor paths in nearest-first order. Caller
+ * applies the precedence rule for ties.
+ */
+export async function walkAncestors(cwd, segment) {
+    const out = [];
+    const root = path.parse(cwd).root;
+    let current = path.resolve(cwd);
+    // Guard against pathological loops in case `path.dirname` doesn't
+    // converge on the root for some reason (e.g. test fixtures).
+    for (let i = 0; i < 64 && current.length > 0; i += 1) {
+        const candidate = path.join(current, segment);
+        const real = await safeRealPath(candidate);
+        if (real !== null) {
+            try {
+                const stat = await fs.stat(real);
+                if (stat.isDirectory())
+                    out.push(real);
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (current === root)
+            break;
+        const next = path.dirname(current);
+        if (next === current)
+            break;
+        current = next;
+    }
+    return out;
+}
+function wrapFsError(message, err) {
+    if (err instanceof Error) {
+        const e = new Error(`${message}: ${err.message}`);
+        e.code = err.code;
+        return e;
+    }
+    return new Error(`${message}: ${String(err)}`);
+}
+//# sourceMappingURL=walk.js.map

package/dist/skills/sources/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../src/skills/sources/walk.ts"],"names":[],"mappings":"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"}

package/dist/skills/substitute.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Argument substitutions for skill bodies.
+ *
+ * Per `knowledge/doc/skills.md` §2.1, a skill body can reference:
+ *
+ *   - `$ARGUMENTS` — the full argument string as typed.
+ *   - `$ARGUMENTS[N]` — the Nth shell-parsed argument (0-indexed).
+ *   - `$N` — shorthand for `$ARGUMENTS[N]`.
+ *   - `$<name>` — named argument matched against `arguments:` frontmatter
+ *     (positional mapping — the first name maps to argv[0], etc.).
+ *   - `${CLAUDE_SESSION_ID}` / `${QODO_SESSION_ID}` — current session ID.
+ *   - `${CLAUDE_SKILL_DIR}` / `${QODO_SKILL_DIR}` — canonical absolute path
+ *     of the skill directory.
+ *   - `${CLAUDE_EFFORT}` / `${QODO_EFFORT}` — active effort level.
+ *
+ * Out-of-bounds indexed references stay literal; the engine emits a
+ * `sdk.skill.substitution_warn` event the caller can wire to telemetry.
+ *
+ * The substitution is intentionally **shape-preserving** for unknown
+ * references — a body with `${LITERAL_DOLLAR_AMOUNT}` (no resolver match)
+ * is passed through verbatim. Authors who want a literal `$ARGUMENTS`
+ * unsubstituted can escape with a non-matching prefix.
+ *
+ * Compatibility: both `CLAUDE_*` and `QODO_*` prefixes resolve to the same
+ * value so OSS skills authored for Anthropic Claude Code render correctly.
+ */
+import type { SkillArgument } from './types.js';
+/**
+ * Context passed to {@link substitute}. Every field is optional; missing
+ * fields cause the matching reference to remain literal (and emit a
+ * warning).
+ */
+export interface SubstitutionContext {
+    /** Skill FQN used for telemetry attribution. */
+    readonly skill: string;
+    /** The full argument string as typed by the caller. */
+    readonly argumentsText?: string;
+    /** Shell-parsed argv. Index `0` corresponds to the first argument. */
+    readonly argv?: readonly string[];
+    /** Named-argument descriptors from frontmatter. Position-mapped onto argv. */
+    readonly named?: readonly SkillArgument[];
+    /** Session identifier resolved by the consumer; powers ${CLAUDE_SESSION_ID}. */
+    readonly sessionId?: string;
+    /** Canonical absolute path of the skill directory; powers ${CLAUDE_SKILL_DIR}. */
+    readonly skillDir?: string;
+    /** Effort string (`low|medium|high|max`); powers ${CLAUDE_EFFORT}. */
+    readonly effort?: string;
+}
+/** Warning produced during substitution — caller forwards to telemetry. */
+export interface SubstitutionWarning {
+    readonly reference: string;
+    readonly reason: 'out_of_bounds' | 'unknown_named' | 'malformed';
+}
+export interface SubstitutionResult {
+    readonly text: string;
+    readonly warnings: readonly SubstitutionWarning[];
+    /**
+     * `true` iff `$ARGUMENTS` (or any of its forms) appeared in the body and
+     * was consumed. Callers use this to decide whether to append
+     * `\nARGUMENTS: <args>\n` when an argument string was supplied but no
+     * reference consumed it — matches Claude Code's append-on-absence behavior.
+     */
+    readonly referencedArguments: boolean;
+}
+/**
+ * Apply substitutions to a skill body. Pure function — IO-free, returns
+ * the rendered text plus any warnings. The caller appends the
+ * `ARGUMENTS:` trailer when:
+ *
+ *   - the caller supplied a non-empty `argumentsText` AND
+ *   - the body did not consume `$ARGUMENTS` / `$N` / `$<name>` in any form.
+ */
+export declare function substitute(body: string, ctx: SubstitutionContext): SubstitutionResult;
+/**
+ * Helper composing `substitute` + the Claude-Code-compatible
+ * append-on-absence behavior. If the caller passed an argument string but
+ * the body never referenced it, append `\nARGUMENTS: <args>\n` to the body.
+ */
+export declare function substituteWithArgumentsTrailer(body: string, ctx: SubstitutionContext): SubstitutionResult;
+/**
+ * Parse a shell-quoted argument string into `argv`. Supports double-quoted
+ * substrings, single-quoted substrings, and backslash escaping inside
+ * double quotes. Intentionally minimal — skill arguments are typed by the
+ * model and not a shell.
+ */
+export declare function parseArgv(s: string): string[];
+//# sourceMappingURL=substitute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"substitute.d.ts","sourceRoot":"","sources":["../../src/skills/substitute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,GAAG,WAAW,CAAC;CAClE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,kBAAkB,CAqJrF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,mBAAmB,GACvB,kBAAkB,CAgBpB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAqE7C"}

package/dist/skills/substitute.js

@@ -0,0 +1,322 @@
+/**
+ * Argument substitutions for skill bodies.
+ *
+ * Per `knowledge/doc/skills.md` §2.1, a skill body can reference:
+ *
+ *   - `$ARGUMENTS` — the full argument string as typed.
+ *   - `$ARGUMENTS[N]` — the Nth shell-parsed argument (0-indexed).
+ *   - `$N` — shorthand for `$ARGUMENTS[N]`.
+ *   - `$<name>` — named argument matched against `arguments:` frontmatter
+ *     (positional mapping — the first name maps to argv[0], etc.).
+ *   - `${CLAUDE_SESSION_ID}` / `${QODO_SESSION_ID}` — current session ID.
+ *   - `${CLAUDE_SKILL_DIR}` / `${QODO_SKILL_DIR}` — canonical absolute path
+ *     of the skill directory.
+ *   - `${CLAUDE_EFFORT}` / `${QODO_EFFORT}` — active effort level.
+ *
+ * Out-of-bounds indexed references stay literal; the engine emits a
+ * `sdk.skill.substitution_warn` event the caller can wire to telemetry.
+ *
+ * The substitution is intentionally **shape-preserving** for unknown
+ * references — a body with `${LITERAL_DOLLAR_AMOUNT}` (no resolver match)
+ * is passed through verbatim. Authors who want a literal `$ARGUMENTS`
+ * unsubstituted can escape with a non-matching prefix.
+ *
+ * Compatibility: both `CLAUDE_*` and `QODO_*` prefixes resolve to the same
+ * value so OSS skills authored for Anthropic Claude Code render correctly.
+ */
+/**
+ * Apply substitutions to a skill body. Pure function — IO-free, returns
+ * the rendered text plus any warnings. The caller appends the
+ * `ARGUMENTS:` trailer when:
+ *
+ *   - the caller supplied a non-empty `argumentsText` AND
+ *   - the body did not consume `$ARGUMENTS` / `$N` / `$<name>` in any form.
+ */
+export function substitute(body, ctx) {
+    const warnings = [];
+    let referencedArguments = false;
+    // Pre-parse argv from `argumentsText` if not explicitly supplied.
+    const argv = ctx.argv ?? (ctx.argumentsText !== undefined ? parseArgv(ctx.argumentsText) : []);
+    const namedMap = buildNamedIndex(ctx.named);
+    // Single-pass scanner. The body length is bounded (skills' soft cap is
+    // 500 lines), so a manual scan is no slower than chained `String.replace`
+    // calls and avoids the "leftover bracket suffix" bug where a literal
+    // `$ARGUMENTS[-1]` from the first pass gets its prefix consumed by the
+    // second pass.
+    let out = '';
+    let i = 0;
+    while (i < body.length) {
+        const ch = body[i];
+        if (ch !== '$') {
+            out += ch;
+            i += 1;
+            continue;
+        }
+        // `${VAR}` envvar reference.
+        if (body[i + 1] === '{') {
+            const close = body.indexOf('}', i + 2);
+            if (close !== -1) {
+                const name = body.slice(i + 2, close);
+                if (/^[A-Z_][A-Z0-9_]*$/.test(name)) {
+                    const resolved = resolveEnvAlias(name, ctx);
+                    if (resolved !== null) {
+                        out += resolved;
+                        i = close + 1;
+                        continue;
+                    }
+                    // Known shape but no resolver match — pass through literally.
+                    out += body.slice(i, close + 1);
+                    i = close + 1;
+                    continue;
+                }
+            }
+            out += ch;
+            i += 1;
+            continue;
+        }
+        // `$ARGUMENTS` and `$ARGUMENTS[N]`.
+        if (body.slice(i, i + '$ARGUMENTS'.length) === '$ARGUMENTS') {
+            const tail = i + '$ARGUMENTS'.length;
+            // `$ARGUMENTS[...]` — the bracket form. Match `[<digits-or-leading-minus>]`
+            // for a valid index; anything else inside the brackets is "malformed"
+            // and the entire `$ARGUMENTS[...]` token stays literal with a
+            // `malformed` warning.
+            if (body[tail] === '[') {
+                const close = body.indexOf(']', tail + 1);
+                if (close !== -1) {
+                    const idxStr = body.slice(tail + 1, close);
+                    if (/^-?\d+$/.test(idxStr)) {
+                        const idx = Number.parseInt(idxStr, 10);
+                        if (idx < 0 || idx >= argv.length) {
+                            // Reference is shape-valid but the index doesn't resolve.
+                            // `referencedArguments` stays false — the value never lands
+                            // in the output, so the append-on-absence trailer should
+                            // still fire (Qodo #2).
+                            warnings.push({ reference: `$ARGUMENTS[${idxStr}]`, reason: 'out_of_bounds' });
+                            out += `$ARGUMENTS[${idxStr}]`;
+                        }
+                        else {
+                            referencedArguments = true;
+                            out += argv[idx];
+                        }
+                        i = close + 1;
+                        continue;
+                    }
+                    // Malformed bracket (non-numeric, empty, leading whitespace).
+                    // Keep the entire `$ARGUMENTS[...]` literal and emit a
+                    // `malformed` warning. Crucially, advance past the closing `]`
+                    // so the bare-`$ARGUMENTS` branch below doesn't then consume
+                    // the `$ARGUMENTS` prefix and leave a dangling `[...]` suffix.
+                    warnings.push({
+                        reference: `$ARGUMENTS[${idxStr}]`,
+                        reason: 'malformed',
+                    });
+                    out += `$ARGUMENTS[${idxStr}]`;
+                    i = close + 1;
+                    continue;
+                }
+                // Unclosed bracket — `$ARGUMENTS[` with no `]`. Treat as
+                // malformed and keep just the `$ARGUMENTS` prefix literal so
+                // the trailing `[` falls through to ordinary character output.
+                warnings.push({ reference: '$ARGUMENTS[', reason: 'malformed' });
+                out += '$ARGUMENTS';
+                i = tail;
+                continue;
+            }
+            // Bare `$ARGUMENTS`. Require a non-word boundary after.
+            const after = body[tail];
+            if (after === undefined || !/[A-Za-z0-9_]/.test(after)) {
+                referencedArguments = true;
+                out += ctx.argumentsText ?? '';
+                i = tail;
+                continue;
+            }
+        }
+        // `$N` shorthand. `[N]` is whole-token, so `$10` parses as argv[10].
+        if (/^\d/.test(body[i + 1] ?? '')) {
+            let j = i + 1;
+            while (j < body.length && /\d/.test(body[j]))
+                j += 1;
+            const idxStr = body.slice(i + 1, j);
+            // No word-char trailing the number (so `$1abc` is not consumed
+            // as `argv[1] + 'abc'`).
+            const after = body[j];
+            if (after === undefined || !/[A-Za-z_]/.test(after)) {
+                const idx = Number.parseInt(idxStr, 10);
+                if (idx < 0 || idx >= argv.length) {
+                    // Index doesn't resolve — keep the reference literal; do NOT
+                    // mark consumed so the trailer still appends (Qodo #2).
+                    warnings.push({ reference: `$${idxStr}`, reason: 'out_of_bounds' });
+                    out += `$${idxStr}`;
+                }
+                else {
+                    referencedArguments = true;
+                    out += argv[idx];
+                }
+                i = j;
+                continue;
+            }
+        }
+        // `$<name>` named argument.
+        if (namedMap.size > 0 && /[A-Za-z_]/.test(body[i + 1] ?? '')) {
+            let j = i + 1;
+            while (j < body.length && /[A-Za-z0-9_]/.test(body[j]))
+                j += 1;
+            const name = body.slice(i + 1, j);
+            const index = namedMap.get(name);
+            if (index !== undefined) {
+                if (index < 0 || index >= argv.length) {
+                    // Declared name but out of argv bounds — keep literal and do
+                    // NOT mark consumed (Qodo #2).
+                    warnings.push({ reference: `$${name}`, reason: 'out_of_bounds' });
+                    out += `$${name}`;
+                }
+                else {
+                    referencedArguments = true;
+                    out += argv[index];
+                }
+                i = j;
+                continue;
+            }
+        }
+        // No substitution matched — keep the literal `$`.
+        out += ch;
+        i += 1;
+    }
+    return { text: out, warnings, referencedArguments };
+}
+/**
+ * Helper composing `substitute` + the Claude-Code-compatible
+ * append-on-absence behavior. If the caller passed an argument string but
+ * the body never referenced it, append `\nARGUMENTS: <args>\n` to the body.
+ */
+export function substituteWithArgumentsTrailer(body, ctx) {
+    const result = substitute(body, ctx);
+    const args = ctx.argumentsText;
+    if (args !== undefined &&
+        args.length > 0 &&
+        !result.referencedArguments) {
+        const sep = result.text.endsWith('\n') ? '' : '\n';
+        return {
+            text: `${result.text}${sep}\nARGUMENTS: ${args}\n`,
+            warnings: result.warnings,
+            referencedArguments: false,
+        };
+    }
+    return result;
+}
+/**
+ * Parse a shell-quoted argument string into `argv`. Supports double-quoted
+ * substrings, single-quoted substrings, and backslash escaping inside
+ * double quotes. Intentionally minimal — skill arguments are typed by the
+ * model and not a shell.
+ */
+export function parseArgv(s) {
+    const out = [];
+    let i = 0;
+    let current = '';
+    let inSingle = false;
+    let inDouble = false;
+    let hasCurrent = false;
+    while (i < s.length) {
+        const ch = s[i];
+        if (inSingle) {
+            if (ch === "'") {
+                inSingle = false;
+                i += 1;
+                continue;
+            }
+            current += ch;
+            hasCurrent = true;
+            i += 1;
+            continue;
+        }
+        if (inDouble) {
+            if (ch === '\\' && i + 1 < s.length) {
+                const next = s[i + 1];
+                if (next === '"' || next === '\\' || next === '$' || next === '`') {
+                    current += next;
+                    hasCurrent = true;
+                    i += 2;
+                    continue;
+                }
+            }
+            if (ch === '"') {
+                inDouble = false;
+                i += 1;
+                continue;
+            }
+            current += ch;
+            hasCurrent = true;
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            inSingle = true;
+            hasCurrent = true;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inDouble = true;
+            hasCurrent = true;
+            i += 1;
+            continue;
+        }
+        if (ch === ' ' || ch === '\t' || ch === '\n') {
+            if (hasCurrent) {
+                out.push(current);
+                current = '';
+                hasCurrent = false;
+            }
+            i += 1;
+            continue;
+        }
+        current += ch;
+        hasCurrent = true;
+        i += 1;
+    }
+    if (hasCurrent) {
+        out.push(current);
+    }
+    return out;
+}
+/**
+ * Build a name → argv-index map from the `arguments:` frontmatter list.
+ * The mapping is **positional** — the first declared name maps to
+ * `argv[0]`, the second to `argv[1]`, and so on.
+ */
+function buildNamedIndex(named) {
+    const map = new Map();
+    if (named === undefined)
+        return map;
+    for (let i = 0; i < named.length; i += 1) {
+        const entry = named[i];
+        if (entry.name.length === 0)
+            continue;
+        if (map.has(entry.name))
+            continue; // first declaration wins
+        map.set(entry.name, i);
+    }
+    return map;
+}
+/**
+ * Resolve a `${VAR}` reference. Returns the substituted value or `null`
+ * when the name is not one of the known envvar aliases.
+ */
+function resolveEnvAlias(name, ctx) {
+    switch (name) {
+        case 'CLAUDE_SESSION_ID':
+        case 'QODO_SESSION_ID':
+            return ctx.sessionId ?? null;
+        case 'CLAUDE_SKILL_DIR':
+        case 'QODO_SKILL_DIR':
+            return ctx.skillDir ?? null;
+        case 'CLAUDE_EFFORT':
+        case 'QODO_EFFORT':
+            return ctx.effort ?? null;
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=substitute.js.map