commandmate 0.29.1 → 0.30.0

package/dist/lib/verification/verify-config.js

@@ -0,0 +1,429 @@
+"use strict";
+/**
+ * Loader and validator for `.commandmate/verify.yaml`.
+ *
+ * Canonical spec: docs/design/verification-config.md
+ * Phase 0 reference implementation: .claude/skills/cmate-verify/scripts/verify-run.sh
+ *
+ * Server-only: reads from disk, so import this from API routes / CLI only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerifyConfigError = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.defaultPlannedGateIds = defaultPlannedGateIds;
+exports.validateGateEntries = validateGateEntries;
+exports.loadVerifyConfig = loadVerifyConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+/**
+ * Built-in gate that answers "is there any work here to verify?".
+ *
+ * Declared here rather than in the runner so modules that only reason *about*
+ * gate selection (task contracts) can name it without importing the engine.
+ */
+exports.WORK_EVIDENCE_GATE_ID = 'work-evidence';
+/**
+ * Built-in gate that reconciles the changed files against the contract's
+ * `scope.allow` / `scope.deny` (#1546). Declared alongside work-evidence for the
+ * same reason: `lib/tasks/contract-message.ts` has to name it while resolving a
+ * contract's gate list, and must not pull the engine in to do so.
+ */
+exports.SCOPE_GATE_ID = 'scope';
+/**
+ * Built-in gate that reconciles the *machine* against the snapshot taken when
+ * the task was created (#1740): listening CommandMate servers, `mcbd-*` tmux
+ * sessions, `$HOME` and `~/.commandmate`. `scope` answers what a delegation
+ * changed inside the repository; this answers what it changed outside one.
+ */
+exports.ENV_CLEAN_GATE_ID = 'env-clean';
+/** Gate IDs reserved for built-in gates; using one in `gates` is a config error. */
+exports.RESERVED_GATE_IDS = [
+    exports.WORK_EVIDENCE_GATE_ID,
+    exports.SCOPE_GATE_ID,
+    exports.ENV_CLEAN_GATE_ID,
+];
+exports.VERIFY_CONFIG_RELATIVE_PATH = '.commandmate/verify.yaml';
+/**
+ * Gate ids a default full run executes, in the order the runner records them
+ * (Issue #2061).
+ *
+ * The Verification pane needs a denominator while a run is in flight — gate
+ * rows are created as each gate starts, so "3 gates recorded" is progress, not
+ * a total. Declared here rather than in the pane because the composition is the
+ * runner's: `work-evidence`, then `scope`, then `env-clean` only when a
+ * declaration switched it on, then verify.yaml's own gates in file order.
+ *
+ * A *default* run, which is what the pane's "run verification" button starts.
+ * A run narrowed with `--gates` / `gateIds` executes a subset of this.
+ *
+ * @param contractGates gate definitions the worktree's execution contract
+ *        carries (#1791). They run after verify.yaml's, exactly as
+ *        `declaredGates()` orders them, and leaving them out understated both
+ *        the pane's progress denominator and — since #2063 made the list
+ *        selectable — which gates an operator is allowed to re-run: a run whose
+ *        only failure was a contract gate offered nothing to re-run at all.
+ */
+function defaultPlannedGateIds(config, contractGates = []) {
+    return [
+        exports.WORK_EVIDENCE_GATE_ID,
+        exports.SCOPE_GATE_ID,
+        ...(config.options.requireEnvClean ? [exports.ENV_CLEAN_GATE_ID] : []),
+        ...config.gates.map((gate) => gate.id),
+        // A contract gate whose id collides with verify.yaml is refused at send
+        // (#1791) and the runner refuses it again, so no de-duplication is needed
+        // here; a duplicate id would be a bug worth seeing rather than hiding.
+        ...contractGates.map((gate) => gate.id),
+    ];
+}
+exports.DEFAULT_TIMEOUT_SEC = 600;
+exports.DEFAULT_MAX_LOG_TAIL_BYTES = 8192;
+const MIN_TIMEOUT_SEC = 1;
+const MAX_TIMEOUT_SEC = 7200;
+const MAX_LOG_TAIL_BYTES = 1048576;
+/**
+ * Shape a gate id may take, wherever a gate is declared.
+ *
+ * Exported because the task contract declares gates too (#1791) and names them
+ * in `verify.gates`. A second copy of this expression would let the two
+ * declaration sites drift into accepting different ids, and a contract gate the
+ * runner refuses to resolve is a completion criterion nothing can evaluate.
+ */
+exports.GATE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/**
+ * Shape a `mutex` name may take (Issue #1771).
+ *
+ * Wider than {@link GATE_ID_PATTERN} because a mutex names a *resource*, not a
+ * gate: two repositories that both bind port 60303 should be able to agree on
+ * `port.60303` and be serialized against each other. Narrow enough that the
+ * name is safe as a path segment — no separator, no whitespace, nothing a shell
+ * re-interprets — because both runners turn it into
+ * `~/.commandmate/locks/<name>.lock`.
+ */
+exports.GATE_MUTEX_PATTERN = /^[A-Za-z0-9_.-]+$/;
+/** Keeps the lock directory name inside every filesystem's limit. */
+exports.MAX_GATE_MUTEX_LENGTH = 64;
+/**
+ * Largest `retryOnFail` a gate may declare (Issue #1772).
+ *
+ * Deliberately 1, and deliberately a named constant rather than a literal in
+ * one `if`: the ceiling is the feature. A gate that may re-run until it passes
+ * reports the machine's luck, not the work.
+ */
+exports.MAX_RETRY_ON_FAIL = 1;
+const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'retryOnFail', 'flakyIsPass'];
+const OPTION_KEYS = [
+    'baseRef',
+    'skipInPrimaryCheckout',
+    'maxLogTailBytes',
+    'requireCommit',
+    'requireEnvClean',
+];
+class VerifyConfigError extends Error {
+    issues;
+    constructor(issues) {
+        super(`invalid verify config:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
+        this.name = 'VerifyConfigError';
+        this.issues = issues;
+    }
+}
+exports.VerifyConfigError = VerifyConfigError;
+function isMapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The bash reference parser strips outer quotes before comparing, so `timeoutSec: "900"`
+ * means 900 there. Accept the same spelling, but only an exact decimal literal.
+ */
+function asInteger(value) {
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+function asBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return null;
+}
+function describe(value) {
+    if (value === undefined)
+        return 'nothing';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return 'a list';
+    if (typeof value === 'object')
+        return 'a mapping';
+    return String(value);
+}
+function collectUnknownKeys(mapping, allowed, at, issues) {
+    for (const key of Object.keys(mapping)) {
+        if (!allowed.includes(key)) {
+            issues.push(`${at}: unknown key "${key}" (v1 is a closed set)`);
+        }
+    }
+}
+/**
+ * Validate a list of `{ id, command, timeoutSec }` entries.
+ *
+ * Shared with the task contract's `verify.gateDefinitions` (#1791), which
+ * declares gates in the same shape and must be held to the same constraints —
+ * id pattern, reserved ids, duplicates, integer timeout in range. Calling this
+ * is what makes "the same constraints" a fact rather than a comment: a contract
+ * gate accepted here is one the runner can execute and the report can name.
+ *
+ * Deliberately does *not* decide whether the list may be absent or empty. That
+ * is the caller's rule: verify.yaml requires at least one gate, a contract that
+ * declares none is the normal case.
+ *
+ * @param at path prefix for issue messages (`gates`, `verify.gateDefinitions`)
+ * @returns the accepted entries; an entry that produced an issue is dropped so
+ *          the result never carries a value that failed validation
+ */
+function validateGateEntries(value, at, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${at}: must be a list (got ${describe(value)})`);
+        return [];
+    }
+    const gates = [];
+    const seenIds = new Set();
+    value.forEach((entry, index) => {
+        const entryAt = `${at}[${index}]`;
+        validateGateEntry(entry, entryAt, seenIds, gates, issues);
+    });
+    return gates;
+}
+/** One gate entry; accepted entries are appended to `gates`. */
+function validateGateEntry(entry, at, seenIds, gates, issues) {
+    const issuesBefore = issues.length;
+    if (!isMapping(entry)) {
+        issues.push(`${at}: must be a mapping (got ${describe(entry)})`);
+        return;
+    }
+    collectUnknownKeys(entry, GATE_KEYS, at, issues);
+    if (typeof entry.id !== 'string' || entry.id === '') {
+        issues.push(`${at}.id: required, must be a non-empty string (got ${describe(entry.id)})`);
+    }
+    else if (!exports.GATE_ID_PATTERN.test(entry.id)) {
+        issues.push(`${at}.id: "${entry.id}" must match ${exports.GATE_ID_PATTERN.source}`);
+    }
+    else if (exports.RESERVED_GATE_IDS.includes(entry.id)) {
+        issues.push(`${at}.id: "${entry.id}" is reserved for a built-in gate`);
+    }
+    else if (seenIds.has(entry.id)) {
+        issues.push(`${at}.id: duplicate gate id "${entry.id}"`);
+    }
+    else {
+        seenIds.add(entry.id);
+    }
+    if (typeof entry.command !== 'string' || entry.command.trim() === '') {
+        issues.push(`${at}.command: required, must be a non-empty string (got ${describe(entry.command)})`);
+    }
+    let timeoutSec = exports.DEFAULT_TIMEOUT_SEC;
+    if (entry.timeoutSec !== undefined) {
+        const parsed = asInteger(entry.timeoutSec);
+        if (parsed === null) {
+            issues.push(`${at}.timeoutSec: must be an integer (got ${describe(entry.timeoutSec)})`);
+        }
+        else if (parsed < MIN_TIMEOUT_SEC || parsed > MAX_TIMEOUT_SEC) {
+            issues.push(`${at}.timeoutSec: must be ${MIN_TIMEOUT_SEC}..${MAX_TIMEOUT_SEC} (got ${parsed})`);
+        }
+        else {
+            timeoutSec = parsed;
+        }
+    }
+    let mutex;
+    if (entry.mutex !== undefined) {
+        if (typeof entry.mutex !== 'string' || entry.mutex === '') {
+            issues.push(`${at}.mutex: must be a non-empty string (got ${describe(entry.mutex)})`);
+        }
+        else if (entry.mutex.length > exports.MAX_GATE_MUTEX_LENGTH) {
+            issues.push(`${at}.mutex: must be at most ${exports.MAX_GATE_MUTEX_LENGTH} characters (got ${entry.mutex.length})`);
+        }
+        else if (!exports.GATE_MUTEX_PATTERN.test(entry.mutex)) {
+            issues.push(`${at}.mutex: "${entry.mutex}" must match ${exports.GATE_MUTEX_PATTERN.source}`);
+        }
+        else {
+            mutex = entry.mutex;
+        }
+    }
+    let retryOnFail;
+    if (entry.retryOnFail !== undefined) {
+        const parsed = asInteger(entry.retryOnFail);
+        if (parsed === null) {
+            issues.push(`${at}.retryOnFail: must be an integer (got ${describe(entry.retryOnFail)})`);
+        }
+        else if (parsed < 0 || parsed > exports.MAX_RETRY_ON_FAIL) {
+            // Not "at most N": the range is the contract. See MAX_RETRY_ON_FAIL.
+            issues.push(`${at}.retryOnFail: must be 0 or ${exports.MAX_RETRY_ON_FAIL} (got ${parsed})`);
+        }
+        else {
+            retryOnFail = parsed;
+        }
+    }
+    let flakyIsPass;
+    if (entry.flakyIsPass !== undefined) {
+        const parsed = asBoolean(entry.flakyIsPass);
+        if (parsed === null) {
+            issues.push(`${at}.flakyIsPass: must be true or false (got ${describe(entry.flakyIsPass)})`);
+        }
+        else if (parsed && retryOnFail !== exports.MAX_RETRY_ON_FAIL) {
+            // A knob that can never fire is a config bug, not a preference: without a
+            // retry the gate has no FLAKY outcome for this to reclassify, so the
+            // declaration reads as "flakes are tolerated here" while changing nothing.
+            issues.push(`${at}.flakyIsPass: true requires retryOnFail: ${exports.MAX_RETRY_ON_FAIL} ` +
+                '(without a retry a gate can never be FLAKY)');
+        }
+        else {
+            flakyIsPass = parsed;
+        }
+    }
+    if (issues.length === issuesBefore) {
+        const gate = {
+            id: entry.id,
+            command: entry.command,
+            timeoutSec,
+        };
+        // Only set when declared: an explicit `mutex: undefined` would serialize
+        // into a contract's stored JSON as a key, and "declared without a value"
+        // is not a state this field has. The same holds for the #1772 pair, whose
+        // absence has to keep meaning "this gate runs exactly once".
+        if (mutex !== undefined)
+            gate.mutex = mutex;
+        if (retryOnFail !== undefined)
+            gate.retryOnFail = retryOnFail;
+        if (flakyIsPass !== undefined)
+            gate.flakyIsPass = flakyIsPass;
+        gates.push(gate);
+    }
+}
+function validateGates(value, issues) {
+    if (value === undefined || value === null) {
+        issues.push('gates: required, at least one gate must be defined');
+        return [];
+    }
+    if (Array.isArray(value) && value.length === 0) {
+        issues.push('gates: at least one gate must be defined');
+        return [];
+    }
+    return validateGateEntries(value, 'gates', issues);
+}
+function validateOptions(value, issues) {
+    const options = {
+        baseRef: null,
+        skipInPrimaryCheckout: true,
+        maxLogTailBytes: exports.DEFAULT_MAX_LOG_TAIL_BYTES,
+        requireCommit: false,
+        requireEnvClean: false,
+    };
+    // A childless `options:` key parses as null and means "all defaults".
+    if (value === undefined || value === null)
+        return options;
+    if (!isMapping(value)) {
+        issues.push(`options: must be a mapping (got ${describe(value)})`);
+        return options;
+    }
+    collectUnknownKeys(value, OPTION_KEYS, 'options', issues);
+    if (value.baseRef !== undefined) {
+        if (typeof value.baseRef !== 'string' || value.baseRef.trim() === '') {
+            issues.push(`options.baseRef: must be a non-empty string (got ${describe(value.baseRef)})`);
+        }
+        else {
+            options.baseRef = value.baseRef;
+        }
+    }
+    if (value.skipInPrimaryCheckout !== undefined) {
+        const parsed = asBoolean(value.skipInPrimaryCheckout);
+        if (parsed === null) {
+            issues.push(`options.skipInPrimaryCheckout: must be true or false (got ${describe(value.skipInPrimaryCheckout)})`);
+        }
+        else {
+            options.skipInPrimaryCheckout = parsed;
+        }
+    }
+    if (value.requireCommit !== undefined) {
+        const parsed = asBoolean(value.requireCommit);
+        if (parsed === null) {
+            issues.push(`options.requireCommit: must be true or false (got ${describe(value.requireCommit)})`);
+        }
+        else {
+            options.requireCommit = parsed;
+        }
+    }
+    if (value.requireEnvClean !== undefined) {
+        const parsed = asBoolean(value.requireEnvClean);
+        if (parsed === null) {
+            issues.push(`options.requireEnvClean: must be true or false (got ${describe(value.requireEnvClean)})`);
+        }
+        else {
+            options.requireEnvClean = parsed;
+        }
+    }
+    if (value.maxLogTailBytes !== undefined) {
+        const parsed = asInteger(value.maxLogTailBytes);
+        if (parsed === null) {
+            issues.push(`options.maxLogTailBytes: must be an integer (got ${describe(value.maxLogTailBytes)})`);
+        }
+        else if (parsed < 0 || parsed > MAX_LOG_TAIL_BYTES) {
+            issues.push(`options.maxLogTailBytes: must be 0..${MAX_LOG_TAIL_BYTES} (got ${parsed})`);
+        }
+        else {
+            options.maxLogTailBytes = parsed;
+        }
+    }
+    return options;
+}
+function parseVerifyConfig(raw, configPath) {
+    let document;
+    try {
+        document = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        throw new VerifyConfigError([`${configPath}: YAML parse error: ${error.message}`]);
+    }
+    if (!isMapping(document)) {
+        throw new VerifyConfigError([
+            `${configPath}: expected a YAML mapping at the top level (got ${describe(document)})`,
+        ]);
+    }
+    const issues = [];
+    collectUnknownKeys(document, TOP_LEVEL_KEYS, 'top level', issues);
+    if (!('version' in document)) {
+        issues.push('version: required, v1 configs must declare "version: 1"');
+    }
+    else if (asInteger(document.version) !== 1) {
+        issues.push(`version: must be 1 (got ${describe(document.version)})`);
+    }
+    const gates = validateGates(document.gates, issues);
+    const options = validateOptions(document.options, issues);
+    if (issues.length > 0)
+        throw new VerifyConfigError(issues);
+    return { version: 1, gates, options };
+}
+/**
+ * Read and validate `<repoPath>/.commandmate/verify.yaml`.
+ *
+ * @returns the validated config, or null when the file does not exist
+ * @throws VerifyConfigError with every violation collected in `issues`
+ */
+function loadVerifyConfig(repoPath) {
+    const configPath = (0, path_1.join)(repoPath, exports.VERIFY_CONFIG_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(configPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new VerifyConfigError([`${configPath}: ${error.message}`]);
+    }
+    return parseVerifyConfig(raw, configPath);
+}

package/dist/lib/verification/verify-draft.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Draft a `.commandmate/verify.yaml` from what a repository already declares
+ * as "passing" (Issue #2061).
+ *
+ * The single implementation of that drafting step. `commandmate verify init`
+ * calls it directly, `POST /api/worktrees/:id/verify/config` calls it for the
+ * Verification pane's "draft from CI" button, and the `cmate-verify` Skill's
+ * step 1 describes this same priority order in prose for environments that have
+ * no CommandMate installed. Two scanners would drift, and a repository whose
+ * gates differ depending on *which* surface drafted them is worse than one with
+ * no drafter at all.
+ *
+ * The priority order is `.claude/skills/cmate-verify/SKILL.md` step 1's:
+ * the CI workflow definitions first — they are the repository's existing answer
+ * to "what has to be green" — then `package.json` scripts as a supplement for
+ * the canonical names CI did not happen to run.
+ *
+ * **What is deliberately NOT drafted.** A gate is a command that may be re-run
+ * any number of times with no outward effect, so publish / deploy / audit /
+ * install steps are refused rather than emitted commented-out-and-forgotten,
+ * and every refusal is reported with its reason: a draft that silently drops
+ * half of CI reads as "CI only checks these four things".
+ *
+ * Output constraints — the rendered YAML has to be readable by BOTH runners:
+ * the product loader (`verify-config.ts`, a real YAML parser) and the Skill's
+ * standalone `verify-run.sh` (awk over a closed YAML subset: two-space indent,
+ * one-line scalars, comments only on their own line). The subset is the
+ * narrower of the two, so this renderer targets it.
+ *
+ * Server-only: reads from disk. Imported by the CLI through a relative path
+ * (`tsconfig.cli.json` resets `paths` to `{}`), so it must not reach for
+ * anything the CLI bundle cannot carry — `fs` / `path` / `yaml` only.
+ *
+ * @module lib/verification/verify-draft
+ */
+/** Where a drafted command was read from. */
+export type DraftSourceKind = 'workflow' | 'npm-script';
+/** Provenance of one drafted (or refused) command. */
+export interface DraftSource {
+    kind: DraftSourceKind;
+    /** Repository-relative file the command was read from. */
+    file: string;
+    /** Workflow job key (`kind === 'workflow'`). */
+    job?: string;
+    /** Workflow step `name:`, or `step <n>` when the step declared none. */
+    step?: string;
+    /** `scripts` key (`kind === 'npm-script'`). */
+    script?: string;
+}
+/**
+ * Why a command found in CI is not a gate.
+ *
+ * Reported rather than dropped. The reader of a draft has to be able to tell
+ * "CI runs nothing else" from "CI runs eight more things this tool refuses to
+ * turn into gates", and only the second is true of a real repository.
+ */
+export type DraftExclusionReason = 
+/** Dependency / toolchain installation; not a check. */
+'setup'
+/** Talks to a registry or the network, so its verdict is not about the tree. */
+ | 'network'
+/** Publishes, deploys or pushes — an outward effect a gate must never have. */
+ | 'release'
+/** Needs a container runtime the worktree is not guaranteed to have. */
+ | 'container'
+/** Rewrites the tree it is supposed to be judging (`lint --fix`, formatters). */
+ | 'mutating'
+/** Minutes-long browser suites; declared gates run on every verification. */
+ | 'long-running'
+/** A multi-line `run:` block, which the YAML subset cannot carry. */
+ | 'multi-line'
+/** Shell composition (`&&`, `|`, `;`, redirection) outside quotes. */
+ | 'multi-command'
+/** Uses `${{ }}` or a runner-only variable, so it cannot run in a worktree. */
+ | 'runner-specific'
+/** Contains both quote characters, so no one-line scalar can carry it. */
+ | 'unquotable'
+/** Its natural id collides with a built-in gate id. */
+ | 'reserved-id'
+/** Prints a message; nothing is judged. */
+ | 'not-a-check'
+/** A watcher (`vitest`, `--watch`): it never exits, so it can only time out. */
+ | 'interactive'
+/** An umbrella script whose narrower suites are already gates. */
+ | 'redundant';
+/** Coarse kind of check, which decides ordering and the default timeout. */
+export type DraftGateCategory = 'guard' | 'lint' | 'typecheck' | 'build' | 'test' | 'other';
+/** One gate the draft proposes. */
+export interface DraftGate {
+    id: string;
+    command: string;
+    timeoutSec: number;
+    category: DraftGateCategory;
+    source: DraftSource;
+}
+/** One command the scan found and refused to turn into a gate. */
+export interface DraftExclusion {
+    command: string;
+    reason: DraftExclusionReason;
+    source: DraftSource;
+}
+/** Everything one scan of a repository produced. */
+export interface VerifyDraft {
+    gates: DraftGate[];
+    excluded: DraftExclusion[];
+    /** Repository-relative files that existed and were read. */
+    scanned: string[];
+}
+/**
+ * Scan a repository and propose gates.
+ *
+ * Never throws for a malformed workflow: a repository with one unparseable YAML
+ * file still has a usable answer in the others, and a drafter that refuses
+ * everything because of one file sends the reader back to writing the config by
+ * hand — which is the state this exists to end.
+ */
+export declare function draftVerifyGates(repoPath: string): VerifyDraft;
+/** Refusal reason for a command, or null when it may become a gate. */
+export declare function refuse(command: string): DraftExclusionReason | null;
+/**
+ * Gate id for a command.
+ *
+ * Reads the *command*, not the CI step's `name:`. Step names are prose
+ * ("Run ESLint", "Build Next.js") in whatever language the workflow is written
+ * in, while `npm run lint` names the same gate in every repository — and the id
+ * is what a task contract's `verify.gates` and `commandmate verify --gates`
+ * have to spell.
+ */
+export declare function deriveGateId(command: string): string;
+/**
+ * Quote character a one-line YAML scalar can carry this command in, or null.
+ *
+ * `verify-run.sh` strips one pair of outer quotes and performs no unescaping,
+ * so the only spellings both parsers agree on are "wrapped in a quote character
+ * the command does not itself contain". A backslash rules out double quotes for
+ * the same reason: the YAML parser would unescape it and awk would not.
+ */
+export declare function quoteFor(command: string): '"' | "'" | null;
+/**
+ * Render a draft as `.commandmate/verify.yaml` v1.
+ *
+ * Inside the Skill runner's YAML subset: two-space indent, one-line scalars,
+ * comments only on lines of their own. Provenance is a comment above each gate
+ * because the first question asked of a generated config is "where did this
+ * come from, and may I delete it".
+ */
+export declare function renderVerifyYaml(draft: VerifyDraft): string;
+/** One line of provenance: which file, which job, which step. */
+export declare function describeSource(source: DraftSource): string;
+/** Why {@link writeVerifyConfigDraft} declined to write. */
+export type DraftRefusal = 'exists' | 'no-gates';
+export interface DraftWriteResult {
+    created: boolean;
+    /** Absolute path of the config, whether or not it was written. */
+    configPath: string;
+    /** The same path, repository-relative, for messages. */
+    relativePath: string;
+    draft: VerifyDraft;
+    /** Rendered YAML — the file's content when created, the proposal otherwise. */
+    yaml: string;
+    refusedBecause?: DraftRefusal;
+}
+/**
+ * What {@link writeVerifyConfigDraft} would do, without touching the disk.
+ *
+ * `created` is always false here — nothing was. `refusedBecause` carries the
+ * same vocabulary the writer uses, so `commandmate verify init --dry-run` and a
+ * real run report the same thing about the same repository instead of the
+ * preview growing its own idea of when a draft is refused.
+ */
+export declare function planVerifyConfigDraft(repoPath: string): DraftWriteResult;
+/**
+ * Draft and write `<repoPath>/.commandmate/verify.yaml`.
+ *
+ * **Never overwrites.** An existing config is the repository's own judgement of
+ * what passing means, usually with the reasoning for each gate in comments
+ * beside it; regenerating over it would replace a considered file with a guess
+ * and destroy the reasoning, and no `--force` is offered because "I meant to
+ * throw it away" is spelled by deleting the file.
+ */
+export declare function writeVerifyConfigDraft(repoPath: string): DraftWriteResult;
+//# sourceMappingURL=verify-draft.d.ts.map

package/dist/lib/verification/verify-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-draft.d.ts","sourceRoot":"","sources":["../../../src/lib/verification/verify-draft.ts"],"names":[],"mappings":"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"}