@ashlr/hub 2.2.0

package/dist/core/providers.js

@@ -0,0 +1,250 @@
+/**
+ * Provider registry — probes local-model endpoints (LM Studio, Ollama) and
+ * resolves the active provider from the configured chain.
+ *
+ * Rules:
+ *  - NEVER throws; all probes return typed results with up:false on failure.
+ *  - Uses global fetch (Node 22+) with a 2-second AbortController timeout.
+ *  - Cloud providers (e.g. 'anthropic') are treated as up when the relevant
+ *    env var is present (ANTHROPIC_API_KEY), else skipped.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Ensure a base URL has the expected path suffix.
+ * e.g. ensurePath('http://localhost:1234', '/v1/models') -> 'http://localhost:1234/v1/models'
+ * If the URL already ends with the path, it is returned unchanged.
+ */
+function ensurePath(base, suffix) {
+    const stripped = base.replace(/\/+$/, '');
+    if (stripped.endsWith(suffix))
+        return stripped;
+    return stripped + suffix;
+}
+/**
+ * Parse model names from an LM Studio /v1/models response (OpenAI shape).
+ * Returns empty array on any shape mismatch.
+ */
+function parseLmStudioModels(body) {
+    if (typeof body !== 'object' ||
+        body === null ||
+        !Array.isArray(body['data'])) {
+        return [];
+    }
+    const data = body.data;
+    return data
+        .filter((m) => typeof m['id'] === 'string')
+        .map((m) => m.id);
+}
+/**
+ * Parse model names from an Ollama /api/tags response.
+ * Returns empty array on any shape mismatch.
+ */
+function parseOllamaModels(body) {
+    if (typeof body !== 'object' ||
+        body === null ||
+        !Array.isArray(body['models'])) {
+        return [];
+    }
+    const models = body.models;
+    return models
+        .filter((m) => typeof m['name'] === 'string')
+        .map((m) => m.name);
+}
+/**
+ * Determine which response shape to use for a given probe URL.
+ * - URL ends with /v1/models  → LM Studio (OpenAI) shape
+ * - URL ends with /api/tags   → Ollama shape
+ * - Fallback: try LM Studio shape first, then Ollama
+ */
+function parseModels(url, body) {
+    if (url.endsWith('/v1/models'))
+        return parseLmStudioModels(body);
+    if (url.endsWith('/api/tags'))
+        return parseOllamaModels(body);
+    // Unknown path — try both shapes, take whichever yields results
+    const lm = parseLmStudioModels(body);
+    return lm.length > 0 ? lm : parseOllamaModels(body);
+}
+// ---------------------------------------------------------------------------
+// Cloud provider env-var map
+// Extend as new cloud providers are added to providerChain.
+// ---------------------------------------------------------------------------
+const CLOUD_PROVIDER_ENV = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+    cohere: 'COHERE_API_KEY',
+    groq: 'GROQ_API_KEY',
+};
+/**
+ * Returns true if a cloud provider's API key is present in process.env.
+ * Unknown cloud providers default to false (not considered up).
+ */
+function cloudProviderUp(id) {
+    const envVar = CLOUD_PROVIDER_ENV[id.toLowerCase()];
+    if (!envVar)
+        return false;
+    const val = process.env[envVar];
+    return typeof val === 'string' && val.trim().length > 0;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Probe a single provider endpoint with a 2-second timeout.
+ *
+ * - For LM Studio: GET <url>/v1/models (appended if not already present)
+ * - For Ollama:    GET <url>/api/tags   (appended if not already present)
+ * - For other ids: url is used as-is (caller must supply full probe URL)
+ *
+ * Never throws — returns up:false with an error string on any failure.
+ */
+export async function probeEndpoint(id, url) {
+    // Determine the canonical probe URL
+    let probeUrl;
+    if (id === 'lmstudio') {
+        probeUrl = ensurePath(url, '/v1/models');
+    }
+    else if (id === 'ollama') {
+        probeUrl = ensurePath(url, '/api/tags');
+    }
+    else {
+        probeUrl = url;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2000);
+    try {
+        const response = await fetch(probeUrl, {
+            method: 'GET',
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        });
+        // NOTE: do NOT clearTimeout here — the abort signal must stay armed across
+        // the response-body read below so a server that streams/hangs the body is
+        // still bounded by the 2s timeout. Cleared in the finally block.
+        if (!response.ok) {
+            return {
+                id,
+                url: probeUrl,
+                up: false,
+                models: [],
+                error: `HTTP ${response.status} ${response.statusText}`,
+            };
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            return {
+                id,
+                url: probeUrl,
+                up: false,
+                models: [],
+                error: 'Response body is not valid JSON',
+            };
+        }
+        const models = parseModels(probeUrl, body);
+        return { id, url: probeUrl, up: true, models };
+    }
+    catch (err) {
+        let message;
+        if (err instanceof Error) {
+            message = err.name === 'AbortError' ? 'Probe timed out after 2s' : err.message;
+        }
+        else {
+            message = String(err);
+        }
+        return { id, url: probeUrl, up: false, models: [], error: message };
+    }
+    finally {
+        // Disarm the timeout only after the body read has completed or failed,
+        // so the abort signal bounds both the fetch() and the response.json().
+        clearTimeout(timer);
+    }
+}
+/**
+ * Build the full ProviderRegistry from the current config.
+ *
+ * - Probes cfg.models.lmstudio and cfg.models.ollama in parallel.
+ * - Walks cfg.models.providerChain in order to find the first up provider.
+ * - Cloud providers (e.g. 'anthropic') count as up if their env key exists.
+ * - Local providers not in the config (unknown ids) are skipped gracefully.
+ */
+export async function getProviderRegistry(cfg) {
+    const chain = cfg.models.providerChain;
+    // Probe the two known local endpoints in parallel
+    const [lmResult, ollamaResult] = await Promise.all([
+        probeEndpoint('lmstudio', cfg.models.lmstudio),
+        probeEndpoint('ollama', cfg.models.ollama),
+    ]);
+    // Build a lookup map for the probed local endpoints
+    const localEndpoints = {
+        lmstudio: lmResult,
+        ollama: ollamaResult,
+    };
+    // Assemble the providers list in chain order where possible,
+    // appending any probed endpoints not present in the chain.
+    const seenIds = new Set();
+    const providers = [];
+    for (const providerId of chain) {
+        if (seenIds.has(providerId))
+            continue;
+        seenIds.add(providerId);
+        if (localEndpoints[providerId] !== undefined) {
+            providers.push(localEndpoints[providerId]);
+        }
+        // Cloud providers are not added as ProviderEndpoint entries
+        // (they have no local URL to probe) — they participate only in
+        // activeProvider resolution below.
+    }
+    // Add any probed local endpoints that were not in the chain
+    for (const [id, endpoint] of Object.entries(localEndpoints)) {
+        if (!seenIds.has(id)) {
+            seenIds.add(id);
+            providers.push(endpoint);
+        }
+    }
+    // Resolve activeProvider: first entry in chain that is considered "up"
+    let activeProvider = null;
+    for (const providerId of chain) {
+        const local = localEndpoints[providerId];
+        if (local !== undefined) {
+            if (local.up) {
+                activeProvider = providerId;
+                break;
+            }
+        }
+        else {
+            // Treat as a cloud provider — up if env key is present
+            if (cloudProviderUp(providerId)) {
+                activeProvider = providerId;
+                break;
+            }
+        }
+    }
+    // Failover fallback: if the configured chain yielded no active provider but a
+    // probed local endpoint is actually up (e.g. a custom chain that omits an up
+    // local id), select the first up local endpoint. Keeps default behavior
+    // identical (the default chain already lists both local ids) while making
+    // failover correct for non-default chains.
+    if (activeProvider === null) {
+        for (const endpoint of providers) {
+            if (endpoint.up) {
+                activeProvider = endpoint.id;
+                break;
+            }
+        }
+    }
+    return { providers, activeProvider, chain };
+}
+/**
+ * Convenience wrapper — returns the id of the active provider, or null.
+ */
+export async function resolveActiveProvider(cfg) {
+    const registry = await getProviderRegistry(cfg);
+    return registry.activeProvider;
+}
+//# sourceMappingURL=providers.js.map

package/dist/core/providers.js.map

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

package/dist/core/quality/conventions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * conventions.ts — Read-only PROJECT-STANDARDS probes for a single repo (M27).
+ *
+ * GUARDRAILS (enforced throughout this file):
+ *  - READ-ONLY: pure FS reads (existsSync / statSync / readFileSync). NO writes,
+ *    NO git mutations, NO installs, NO shell. NEVER mutates a user repo working tree.
+ *  - Bounded: a fixed, small set of top-level presence checks + a shallow read of
+ *    the root package.json; no deep tree traversal, no unbounded loops.
+ *  - Never throws: returns [] on any error so callers (health.ts) stay unblocked.
+ *  - No secrets: emitted ConventionFinding values are presence/label metadata only.
+ *  - Enrollment-scoping is the CALLER's responsibility (health.ts) — this module
+ *    is a pure probe over whatever absolute path it is handed.
+ */
+import type { ConventionFinding } from '../types.js';
+/**
+ * Probe `repo` (an absolute path) for project-standard conventions.
+ *
+ * Returns a deterministic, ordered ConventionFinding[] covering:
+ *  - README presence + thinness (< THIN_README_BYTES bytes)
+ *  - LICENSE presence
+ *  - lockfile presence (package-lock.json / yarn.lock / pnpm-lock.yaml / bun.lockb / Cargo.lock / …)
+ *  - .gitignore presence
+ *  - a test signal (test|tests|__tests__|spec dir, or a package.json "test" script)
+ *  - a CI config presence (.github/workflows / .gitlab-ci.yml / .circleci / …)
+ *  - (Node projects only) a package.json `license` field
+ *  - (Node projects only) a package.json `repository` field
+ *
+ * Pure FS reads, bounded (fixed check list + one shallow package.json read; no
+ * deep traversal), NEVER mutates, NEVER throws (returns [] on failure).
+ *
+ * Mirrors the read-only presence/size heuristics in
+ * portfolio/scanners.ts#scanDocs / #scanTests. Enrollment-scoping is the
+ * caller's responsibility (health.ts).
+ */
+export declare function probeConventions(repo: string): ConventionFinding[];

package/dist/core/quality/conventions.js

@@ -0,0 +1,267 @@
+/**
+ * conventions.ts — Read-only PROJECT-STANDARDS probes for a single repo (M27).
+ *
+ * GUARDRAILS (enforced throughout this file):
+ *  - READ-ONLY: pure FS reads (existsSync / statSync / readFileSync). NO writes,
+ *    NO git mutations, NO installs, NO shell. NEVER mutates a user repo working tree.
+ *  - Bounded: a fixed, small set of top-level presence checks + a shallow read of
+ *    the root package.json; no deep tree traversal, no unbounded loops.
+ *  - Never throws: returns [] on any error so callers (health.ts) stay unblocked.
+ *  - No secrets: emitted ConventionFinding values are presence/label metadata only.
+ *  - Enrollment-scoping is the CALLER's responsibility (health.ts) — this module
+ *    is a pure probe over whatever absolute path it is handed.
+ */
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Bounds / weights
+// ---------------------------------------------------------------------------
+/** Minimum README size (bytes) below which it is considered "thin". */
+const THIN_README_BYTES = 300;
+/** Fixed candidate name sets (no deep traversal — top-level presence only). */
+const README_NAMES = ['README.md', 'README.txt', 'README', 'readme.md', 'Readme.md'];
+const LICENSE_NAMES = ['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'LICENCE', 'LICENCE.md', 'COPYING'];
+const LOCKFILE_NAMES = [
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    'Cargo.lock',
+    'poetry.lock',
+    'Pipfile.lock',
+    'go.sum',
+    'composer.lock',
+    'Gemfile.lock',
+];
+const TEST_DIR_NAMES = ['test', 'tests', '__tests__', 'spec'];
+const CI_PATHS = ['.github/workflows', '.gitlab-ci.yml', '.circleci', 'azure-pipelines.yml', '.travis.yml'];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** True when ANY of `names` exists directly under `dir`. Never throws. */
+function anyExists(dir, names) {
+    for (const name of names) {
+        try {
+            if (existsSync(join(dir, name)))
+                return true;
+        }
+        catch {
+            // ignore — treat as absent
+        }
+    }
+    return false;
+}
+/** Byte size of the first existing file in `names` under `dir`, else 0. */
+function firstSize(dir, names) {
+    for (const name of names) {
+        const p = join(dir, name);
+        try {
+            if (existsSync(p))
+                return statSync(p).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    return 0;
+}
+/** True when `name` exists directly under `dir` AND is a directory. Never throws. */
+function dirExists(dir, name) {
+    try {
+        const p = join(dir, name);
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Shallow read of a repo's top-level package.json. Returns null when absent or
+ * malformed. Read-only; never throws.
+ */
+function readPackageJson(repo) {
+    const p = join(repo, 'package.json');
+    try {
+        if (!existsSync(p))
+            return null;
+        const raw = readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // malformed — treat as absent
+    }
+    return null;
+}
+/** True when `pkg` has a non-empty "test" script. */
+function hasTestScript(pkg) {
+    if (pkg === null)
+        return false;
+    const scripts = pkg['scripts'];
+    if (scripts === null || typeof scripts !== 'object' || Array.isArray(scripts))
+        return false;
+    const test = scripts['test'];
+    return typeof test === 'string' && test.trim() !== '';
+}
+/** True when `pkg` carries a non-empty string field at `key`. */
+function hasStringField(pkg, key) {
+    const v = pkg[key];
+    return typeof v === 'string' && v.trim() !== '';
+}
+/** True when `pkg` carries a `repository` field (string or object form). */
+function hasRepositoryField(pkg) {
+    const v = pkg['repository'];
+    if (typeof v === 'string')
+        return v.trim() !== '';
+    if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
+        const url = v['url'];
+        return typeof url === 'string' && url.trim() !== '';
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// probeConventions — the single public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Probe `repo` (an absolute path) for project-standard conventions.
+ *
+ * Returns a deterministic, ordered ConventionFinding[] covering:
+ *  - README presence + thinness (< THIN_README_BYTES bytes)
+ *  - LICENSE presence
+ *  - lockfile presence (package-lock.json / yarn.lock / pnpm-lock.yaml / bun.lockb / Cargo.lock / …)
+ *  - .gitignore presence
+ *  - a test signal (test|tests|__tests__|spec dir, or a package.json "test" script)
+ *  - a CI config presence (.github/workflows / .gitlab-ci.yml / .circleci / …)
+ *  - (Node projects only) a package.json `license` field
+ *  - (Node projects only) a package.json `repository` field
+ *
+ * Pure FS reads, bounded (fixed check list + one shallow package.json read; no
+ * deep traversal), NEVER mutates, NEVER throws (returns [] on failure).
+ *
+ * Mirrors the read-only presence/size heuristics in
+ * portfolio/scanners.ts#scanDocs / #scanTests. Enrollment-scoping is the
+ * caller's responsibility (health.ts).
+ */
+export function probeConventions(repo) {
+    try {
+        const findings = [];
+        const pkg = readPackageJson(repo);
+        // 1. README presence + thinness ----------------------------------------
+        const hasReadme = anyExists(repo, README_NAMES);
+        if (!hasReadme) {
+            findings.push({
+                key: 'readme',
+                label: 'README',
+                ok: false,
+                weight: 3,
+                detail: 'No README file found at the repo root.',
+            });
+        }
+        else {
+            const size = firstSize(repo, README_NAMES);
+            const thin = size < THIN_README_BYTES;
+            findings.push({
+                key: 'readme',
+                label: 'README',
+                ok: !thin,
+                weight: 2,
+                detail: thin
+                    ? `README is only ${size} bytes (< ${THIN_README_BYTES}); consider expanding usage/setup.`
+                    : `README present (${size} bytes).`,
+            });
+        }
+        // 2. LICENSE file presence ---------------------------------------------
+        const hasLicenseFile = anyExists(repo, LICENSE_NAMES);
+        findings.push({
+            key: 'license',
+            label: 'LICENSE file',
+            ok: hasLicenseFile,
+            weight: 3,
+            detail: hasLicenseFile
+                ? 'LICENSE file present at the repo root.'
+                : 'No LICENSE file found at the repo root.',
+        });
+        // 3. lockfile presence --------------------------------------------------
+        const hasLockfile = anyExists(repo, LOCKFILE_NAMES);
+        findings.push({
+            key: 'lockfile',
+            label: 'Dependency lockfile',
+            ok: hasLockfile,
+            weight: 3,
+            detail: hasLockfile
+                ? 'A dependency lockfile is present (reproducible installs).'
+                : 'No lockfile found (package-lock.json / yarn.lock / pnpm-lock.yaml / Cargo.lock / …).',
+        });
+        // 4. .gitignore presence ------------------------------------------------
+        const hasGitignore = anyExists(repo, ['.gitignore']);
+        findings.push({
+            key: 'gitignore',
+            label: '.gitignore',
+            ok: hasGitignore,
+            weight: 2,
+            detail: hasGitignore
+                ? '.gitignore present at the repo root.'
+                : 'No .gitignore found at the repo root.',
+        });
+        // 5. test signal: a test dir OR a package.json "test" script -----------
+        const hasTestDir = TEST_DIR_NAMES.some(name => dirExists(repo, name));
+        const testScript = hasTestScript(pkg);
+        const hasTests = hasTestDir || testScript;
+        findings.push({
+            key: 'testdir',
+            label: 'Test suite signal',
+            ok: hasTests,
+            weight: 4,
+            detail: hasTests
+                ? testScript
+                    ? 'package.json defines a "test" script.'
+                    : 'A test directory (test/tests/__tests__/spec) is present.'
+                : 'No test directory or package.json "test" script found.',
+        });
+        // 6. CI config presence -------------------------------------------------
+        // .github/workflows is a directory; the rest are files — anyExists covers both.
+        const hasCi = anyExists(repo, CI_PATHS);
+        findings.push({
+            key: 'ci',
+            label: 'CI configuration',
+            ok: hasCi,
+            weight: 3,
+            detail: hasCi
+                ? 'A CI config is present (.github/workflows / .gitlab-ci.yml / …).'
+                : 'No CI config found (.github/workflows / .gitlab-ci.yml / .circleci / …).',
+        });
+        // 7 & 8. package.json metadata fields (Node projects only) -------------
+        // Only probed when a parseable package.json exists, so non-Node repos are
+        // not penalized for missing npm-specific metadata.
+        if (pkg !== null) {
+            const hasLicenseField = hasStringField(pkg, 'license');
+            findings.push({
+                key: 'pkg-license',
+                label: 'package.json license field',
+                ok: hasLicenseField,
+                weight: 2,
+                detail: hasLicenseField
+                    ? 'package.json declares a "license" field.'
+                    : 'package.json has no "license" field.',
+            });
+            const hasRepo = hasRepositoryField(pkg);
+            findings.push({
+                key: 'pkg-repository',
+                label: 'package.json repository field',
+                ok: hasRepo,
+                weight: 1,
+                detail: hasRepo
+                    ? 'package.json declares a "repository" field.'
+                    : 'package.json has no "repository" field.',
+            });
+        }
+        return findings;
+    }
+    catch {
+        // Any unexpected failure — stay unblocked, report nothing.
+        return [];
+    }
+}
+//# sourceMappingURL=conventions.js.map

package/dist/core/quality/conventions.js.map

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

package/dist/core/quality/fixes.d.ts

@@ -0,0 +1,56 @@
+/**
+ * fixes.ts — Deterministic advisory SAFE FIXES + PROPOSAL emission (M27).
+ *
+ * HARD SAFETY INVARIANTS (enforced throughout this file):
+ *  - PROPOSAL-ONLY: emitFixProposals routes each SafeFix to the M23 Approval
+ *    Inbox via createProposal() as a PENDING proposal (status 'pending', NEVER
+ *    auto-advanced/applied). The default proposal kind is 'note' (advisory, no
+ *    diff), origin 'manual'.
+ *  - READ-ONLY / NO MUTATION: deriveSafeFixes is a pure function of a
+ *    HealthScore. NEITHER function writes to a user repo, writes CONFIG, pushes,
+ *    opens a PR, or deploys. There is NO apply path here.
+ *  - OPTIONAL SANDBOX-PATCH (STRETCH, documented only): if a deterministic fix
+ *    diff is ever generated, it MUST be produced in an M21 sandbox worktree
+ *    (src/core/sandbox/*) and attached to a PENDING 'patch' proposal — NEVER
+ *    written to the real tree, NEVER pushed. The DEFAULT is advisory 'note's.
+ *  - Bounded: caps fixes emitted per run. Never throws (createProposal best-effort).
+ *  - No secrets: SafeFix / proposal fields are advisory metadata only.
+ */
+import type { HealthScore, Proposal, SafeFix } from '../types.js';
+/**
+ * Derive deterministic, advisory SafeFix[] from a per-repo HealthScore.
+ *
+ * Walks the score's failed convention probes (ok === false) and worst offenders,
+ * mapping each actionable, concretely-phraseable gap into an advisory SafeFix:
+ *  - missing LICENSE      -> { dimension:'docs',        key:'docs.add-license' }
+ *  - missing README       -> { dimension:'docs',        key:'docs.add-readme' }
+ *  - missing .gitignore   -> { dimension:'conventions', key:'conventions.add-gitignore' }
+ *  - missing lockfile/CI  -> { dimension:'conventions', key:'conventions.add-{lockfile,ci}' }
+ *  - vulnerable/stale dep  -> { dimension:'deps',        key:'deps.upgrade:<pkg>' }
+ *  - missing test          -> { dimension:'tests',       key:'tests.add-test[:…]' }
+ *  - high TODO debt        -> { dimension:'codeDebt',    key:'codeDebt.resolve:…' }
+ *
+ * Pure function (no I/O), deterministic ordering, deduped by `key`, bounded to
+ * MAX_FIXES_PER_REPO. Every SafeFix defaults to proposalKind 'note' (advisory).
+ * NEVER mutates anything.
+ */
+export declare function deriveSafeFixes(score: HealthScore): SafeFix[];
+/**
+ * Emit each SafeFix as a PENDING M23 Approval Inbox proposal.
+ *
+ * For each fix: createProposal({ repo, origin: 'manual', kind: 'note', title,
+ * summary }) — status is assigned 'pending' BY THE STORE and NEVER auto-advanced.
+ * Default kind is 'note' (advisory, no diff). M27 does NOT apply patches and does
+ * NOT mutate working trees here; this module advances no proposal status, pushes
+ * nothing, opens no PR, and deploys nothing — createProposal() is its ONLY effect.
+ *
+ * (STRETCH, NOT wired by default) A fix with proposalKind 'patch' would require
+ * generating its diff in an M21 sandbox worktree and attaching it as a PENDING
+ * 'patch' proposal with the sandboxId — never written to the real tree. This
+ * build emits NOTES ONLY; any 'patch'-kind SafeFix is downgraded to a 'note'
+ * proposal here (no diff is produced), keeping the inbox advisory.
+ *
+ * Returns the created Proposal[] (pending). Never throws (createProposal is
+ * best-effort and returns the in-memory proposal even on persistence failure).
+ */
+export declare function emitFixProposals(fixes: SafeFix[]): Proposal[];