@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/reviewer/verdict-classifier.d.ts

@@ -0,0 +1,62 @@
+import type { LocalGemmaPlannerRunner } from '../planner/local-gemma';
+import type { AgentKind, ReviewerRole, VerdictKind } from './types';
+/** Per-verdict context (seat/role/agent) — carried for observability; the Gemma
+ *  classification itself is context-free (deterministic on `rawText`). */
+export interface VerdictClassifierContext {
+    seatId: number;
+    role: ReviewerRole;
+    agent: AgentKind;
+}
+/**
+ * A classifier's resolved decision. `reason` is set ONLY on a fail-closed ESCALATE
+ * (a SAFE closed label — never raw model/reviewer text); a genuine reviewer verdict
+ * (incl. a genuine ESCALATE the reviewer actually chose) leaves `reason` undefined
+ * so the provider keeps the reviewer's own reasoning (D5/MED-C).
+ */
+export interface VerdictClassification {
+    verdict: VerdictKind;
+    reason?: string;
+}
+export type VerdictClassifier = (rawText: string, ctx: VerdictClassifierContext) => Promise<VerdictClassification>;
+/** SAFE closed labels for a fail-closed ESCALATE (D3/D5/MED-C). Never raw text. */
+export declare const VERDICT_CLASSIFIER_UNCERTAIN = "verdict_classifier_uncertain";
+export declare const VERDICT_CLASSIFIER_CONFLICT = "verdict_classifier_conflict";
+export declare const VERDICT_CLASSIFIER_UNAVAILABLE = "verdict_classifier_unavailable";
+/**
+ * Build a fail-closed Gemma verdict classifier. Order:
+ *   (1) empty `rawText.trim()===''` → ESCALATE (no `classify` call);
+ *   (2) [D2a] conflicting standalone verdicts → ESCALATE (before Gemma);
+ *   (3) classify (8s race) → validate JSON/enum/`confidence:'high'` per D3;
+ *   (4) REVISE → require `extractSuggestedChanges(postVerdictReasoning(rawText))`
+ *       yields ≥1 change (D5), else ESCALATE.
+ * Whole body try/catch-wrapped; any throw / timeout → ESCALATE (unavailable).
+ * A genuine non-ESCALATE verdict (and a genuine reviewer ESCALATE) returns NO
+ * `reason` so the provider keeps the reviewer's own reasoning.
+ */
+export declare function makeGemmaVerdictClassifier(runner: LocalGemmaPlannerRunner, opts?: {
+    timeoutMs?: number;
+}): VerdictClassifier;
+/**
+ * A trivial classifier that returns ESCALATE (with a closed `reason` label) for
+ * every input, with no runner. Installed by the wiring when flag=`gemma` but the
+ * Gemma runner is null at boot (Ollama unreachable) — so `gemma` mode NEVER
+ * silently degrades to the regex parser (agy-MED-1).
+ */
+export declare function alwaysEscalateClassifier(reason: string): VerdictClassifier;
+/**
+ * [D5] Resolve the `ReviewerVerdict`'s `reasoning` + `suggested_changes` from a
+ * classification, shared by all three providers' `buildVerdict` so the safety-
+ * critical mapping lives in ONE audited place:
+ *  - `reasoning`: a fail-closed ESCALATE (has a closed `reason` label) → that
+ *    label (never raw text, parity with the old `parse_failure`→template); every
+ *    other verdict (incl. a genuine reviewer ESCALATE, `reason` undefined) → the
+ *    reviewer's raw text verbatim.
+ *  - `suggested_changes`: REVISE → `extractSuggestedChanges(postVerdictReasoning(
+ *    rawText))` (non-empty by construction — the classifier already gated it);
+ *    every other verdict → `[]`.
+ */
+export declare function resolveClassifiedVerdictFields(classification: VerdictClassification, rawText: string): {
+    verdict: VerdictKind;
+    reasoning: string;
+    suggested_changes: string[];
+};

package/dist/session/__tests__/prepare-event-timestamp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/__tests__/session-resume-service-keys.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/index.d.ts

@@ -3,3 +3,4 @@ export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult } from './
 export { rekeySessionForNewDevices } from './session-rekey';
 export { startDeviceKeyWatcher } from './device-key-watcher';
 export { registerDeviceEncryptionKey } from './register-device-key';
+export { prepareEventTimestamp, _resetPrepareEventTimestampForTesting, } from './prepare-event-timestamp';

package/dist/session/prepare-event-timestamp.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Returns an ISO-8601 timestamp with millisecond precision that is
+ * STRICTLY GREATER than any previous timestamp returned for the same
+ * `orderingKey` within this process.
+ *
+ * Formula: `Math.max(baseMs, lastMs + 1, floorMs)` where `floorMs` is
+ * `notBeforeMs + 1` when a finite `notBeforeMs` is supplied (else 0), and:
+ *   - baseMs = parsed agentClock if provided (and valid), else Date.now()
+ *   - lastMs = previously-emitted ms for this orderingKey (or 0 if first)
+ *
+ * `agentClock` ANCHORS the timestamp when provided. This is the load-bearing
+ * behavior for agy's transcript replay: agy emits events with their original
+ * `created_at` even during a backfill (so subscription clients see them in
+ * logical order, not in replay-arrival order). For hook-driven plugins
+ * (claude/codex/gemini), `agentClock` is left undefined and baseMs = wallMs.
+ *
+ * Memory: bounded LRU with cap=MAX_LRU_KEYS. Eviction order is least-
+ * recently-touched, so active orderingKeys are never evicted. Resets on
+ * process restart (correct: restart is a new lifecycle).
+ */
+export declare function prepareEventTimestamp(opts: {
+    orderingKey: string;
+    agentClock?: string;
+    notBeforeMs?: number;
+}): string;
+/**
+ * Test-only: clear the per-key map. Used by jest/vitest to reset state
+ * between tests. Not exported from the package root.
+ */
+export declare function _resetPrepareEventTimestampForTesting(): void;

package/dist/session/session-rekey.d.ts

@@ -36,3 +36,43 @@ export interface RekeyOptions {
  * @returns The number of new grants that succeeded.
  */
 export declare function rekeySessionForNewDevices(sessionId: string, sessionKey: string, appSyncClient: AppSyncClient, options?: RekeyOptions): Promise<number>;
+/**
+ * Options for {@link awaitOwnSessionKeyGrant}.
+ */
+export interface AwaitOwnGrantOptions {
+    /** Poll interval in ms. Default 5000. */
+    pollIntervalMs?: number;
+    /** Max poll attempts. Default 6 (30s total at 5s intervals). */
+    maxAttempts?: number;
+    /** Authenticated AppSyncClient. */
+    appSyncClient: AppSyncClient;
+    /** Fired on successful decrypt. Telemetry-only — never thrown. */
+    onSuccess?: (attemptCount: number) => void;
+    /** Fired after maxAttempts exhausted. Telemetry-only — never thrown. */
+    onTimeout?: (attemptCount: number) => void;
+}
+/**
+ * Wait for this device's deviceId to appear in `session.encryptedKeys`.
+ *
+ * Triggered when {@link keychainManager.getSessionKey} returned null on
+ * resume AND at least one other device IS in encryptedKeys (so some other
+ * device can mint a grant for us via grantSessionKey). Caller must have
+ * already invoked {@link registerDeviceEncryptionKey} BEFORE this helper —
+ * that's what causes mobile's DeviceKeyWatcher subscription to fire and
+ * grant the session key to our (possibly rotated) pubKey.
+ *
+ * This helper deliberately bypasses {@link keychainManager.getSessionKey}
+ * (which has a cache short-circuit) and instead:
+ *   1. Calls {@link AppSyncClient.getSession} each poll for fresh
+ *      `encryptedKeys`.
+ *   2. Looks for our `deviceId` in the fresh list.
+ *   3. If found, calls {@link cryptoService.decryptSessionKey} directly.
+ *   4. On success, populates the keychain cache (so subsequent
+ *      `getSessionKey` calls hit the cache). The cache is NEVER populated
+ *      on failure — there's no null sentinel.
+ *
+ * Returns the decrypted session key on success, or `null` after timeout.
+ * Errors are swallowed inside the loop (best-effort polling); telemetry
+ * surfaces success vs timeout via the optional callbacks.
+ */
+export declare function awaitOwnSessionKeyGrant(sessionId: string, options: AwaitOwnGrantOptions): Promise<string | null>;

package/dist/session/session-resume.d.ts

@@ -24,6 +24,30 @@ export interface ResumeOrCreateSessionResult {
     /** The E2E session key (for encrypting/decrypting events), or null if no encryption */
     sessionKey: string | null;
 }
+/**
+ * CP-1.b IMPL r5 H-2 — Typed error thrown by `prepareSessionEncryption()`
+ * when `listServiceDeviceKeys()` returns an empty array across all
+ * attempts. Contract per r6/r7 fix: 4 fetch attempts, 3 backoff sleeps:
+ * 1s/2s/4s (total ~7s wall on full-failure path). Per CP-1.b design
+ * §6.1 lifecycle bullet "Fail-safe:
+ * shell-side createSession retries with 1s + 2s + 4s backoff" + LOCK
+ * #32 (prewarm custom-resource closes the first-cold-start window
+ * structurally; this retry is the disaster-recovery fail-safe).
+ *
+ * Surfacing this as a typed error (rather than the previous
+ * best-effort behavior which built sessions WITHOUT the planner-proxy
+ * grant — guaranteeing every subsequent Lambda decrypt would fail)
+ * lets the plugin / CLI wrappers display an actionable banner to the
+ * user instead of producing a half-broken session.
+ *
+ * The Lambda emits a matching `PlannerProxyServiceKeyMissing`
+ * CloudWatch metric in its `handleClassify` decrypt-failure path; the
+ * shell-side typed error closes the funnel at session-create time so
+ * the user never reaches a session that can't be decrypted.
+ */
+export declare class PlannerProxyServiceKeyMissingError extends Error {
+    constructor(msg: string);
+}
 /**
  * Prepare E2E encryption for a new session.
  *
@@ -36,6 +60,7 @@ export interface ResumeOrCreateSessionResult {
 export declare function prepareSessionEncryption(sessionId: string, appSyncClient: AppSyncClient, logger: Logger): Promise<{
     sessionKey: string;
     encryptedKeys: EncryptedSessionKey[];
+    skippedDeviceIds: string[];
 } | null>;
 /**
  * Resume an existing session or create a new one.

package/dist/structural-summary/__tests__/__fixtures__/fixture-helpers.d.ts

@@ -0,0 +1,11 @@
+export declare function makeTmpDir(prefix?: string): Promise<string>;
+export declare function git(cwd: string, ...args: string[]): Promise<string>;
+export declare function writeFile(file: string, content: string): Promise<void>;
+/**
+ * Initialises a git repo at `dir`, commits initial empty-tree marker so
+ * `git status --porcelain` works.
+ */
+export declare function initGitRepo(dir: string): Promise<void>;
+export declare function gitAdd(cwd: string, file: string): Promise<void>;
+export declare function gitCommit(cwd: string, msg?: string): Promise<void>;
+export declare function cleanup(dir: string): Promise<void>;

package/dist/structural-summary/__tests__/assembler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/generator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/language-detect.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/cargo.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/gomod.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/gradle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/npm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/podfile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/manifest-parsers/pyproject.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/opt-in-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/privacy-filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/safe-file-read.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/user-ignore-matcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/__tests__/walker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/structural-summary/generator.d.ts

@@ -0,0 +1,8 @@
+import { type ExclusionState, type StructuralSummaryGenerator } from './types';
+export declare function createStructuralSummaryGenerator(): StructuralSummaryGenerator;
+export interface ReadmeCounters {
+    excludedAsUntracked: number;
+    excludedByGitignore: number;
+    excludedByIgnoreFile: number;
+}
+export declare function readReadmePreview(rootPath: string, exclusionState: ExclusionState, countedExactPaths: Set<string>, countedPrunedPrefixes: Set<string>, counters: ReadmeCounters): Promise<string>;

package/dist/structural-summary/index.d.ts

@@ -0,0 +1,7 @@
+export { createStructuralSummaryGenerator, readReadmePreview, } from './generator';
+export { walk as walkRepoTree } from './walker';
+export { isPathAdmissible, isPathInIgnoredPrefixes, isPathAccountedFor, matchesSecretDenyList, SECRET_DENY_LIST, } from './privacy-filter';
+export { readOptIn, addBodyPath, removeBodyPath, optInFilePath, } from './opt-in-store';
+export { compileUserIgnore, emptyUserIgnoreMatcher, } from './user-ignore-matcher';
+export type { DirectoryNode, RepoSummary, StructuralSummary, StructuralSummaryGenerator, GenerateOpts, PrivacyEnvelope, WalkResult, ExclusionState, UserIgnoreMatcher, ParsedManifest, ManifestType, OptInFile, StructuralSummaryErrorKind, } from './types';
+export { StructuralSummaryError } from './types';

package/dist/structural-summary/manifest-parsers/cargo.d.ts

@@ -0,0 +1,3 @@
+import { type ParsedManifest } from '../types';
+export declare function findManifest(rootPath: string): Promise<string | null>;
+export declare function parse(file: string): Promise<ParsedManifest>;

package/dist/structural-summary/manifest-parsers/index.d.ts

@@ -0,0 +1,7 @@
+import type { ExclusionState, ParsedManifest } from '../types';
+export interface ManifestCounters {
+    excludedAsUntracked: number;
+    excludedByGitignore: number;
+    excludedByIgnoreFile: number;
+}
+export declare function parse(rootPath: string, exclusionState: ExclusionState, countedExactPaths: Set<string>, countedPrunedPrefixes: Set<string>, counters: ManifestCounters): Promise<ParsedManifest>;

package/dist/structural-summary/manifest-parsers/npm.d.ts

@@ -0,0 +1,3 @@
+import { type ParsedManifest } from '../types';
+export declare function findManifest(rootPath: string): Promise<string | null>;
+export declare function parse(file: string): Promise<ParsedManifest>;

package/dist/structural-summary/manifest-parsers/other.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedManifest } from '../types';
+export declare const pyproject: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};
+export declare const gomod: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};
+export declare const podfile: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};
+export declare const gradle: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};

package/dist/structural-summary/opt-in-store.d.ts

@@ -0,0 +1,24 @@
+import { type OptInFile } from './types';
+import type { Tier } from '../orchestration-shell/types';
+export declare function optInFilePath(): string;
+/**
+ * Per Stage 2 r1 Gemini M-1: reader takes `currentTier`. If
+ * `parsed.tierAtOptIn !== currentTier`, returns `null` (graceful tier-
+ * downgrade invalidation — no error throw).
+ */
+export declare function readOptIn(currentTier: Tier): Promise<OptInFile | null>;
+/**
+ * Per Stage 2 r1 Gemini H-3 option (a): widen to `Tier` so callers can
+ * pass `args.tier` directly without an unsafe type narrow. Runtime gate
+ * inside the function is authoritative; non-MAX throws `tier_gate`.
+ *
+ * Stage 2 r2 fix (H-1, Codex): validates that `bodyPath` is absolute
+ * BEFORE any persistence work. Normalises via `path.resolve()`
+ * (defense-in-depth — strips any residual `..` segments) and resolves
+ * symlinks via `fs.realpath()`. The realpath result is what gets
+ * persisted, so a future `cd` that lands the user in a different repo
+ * cannot trip a relative-path match. Throws `StructuralSummaryError(
+ * 'invalid_path')` for non-absolute or unresolvable inputs.
+ */
+export declare function addBodyPath(bodyPath: string, currentTier: Tier): Promise<OptInFile>;
+export declare function removeBodyPath(bodyPath: string): Promise<OptInFile>;

package/dist/structural-summary/privacy-filter.d.ts

@@ -0,0 +1,110 @@
+import type { ExclusionState } from './types';
+/**
+ * Stage 2 IMPL r2 fix (H-3, Codex H-2): strict path-containment helper.
+ *
+ * Returns true iff `rel` (the output of `path.relative(root, target)`)
+ * denotes a path OUTSIDE `root` via parent-directory traversal. Required
+ * because the naive `rel.startsWith('..')` form falsely classifies valid
+ * child names that happen to BEGIN with `..` (e.g., `..scratch/file.ts`,
+ * `..hidden`, `..foo/bar`) as outside the root.
+ *
+ * Correct semantics:
+ *   rel === '..'                       → outside (parent of root)
+ *   rel === '..' + path.sep + 'sib'    → outside (sibling of root)
+ *   rel === '..' + '/' + 'sib'         → outside (POSIX form, used by
+ *                                        git output / forward-slash
+ *                                        callers on Windows)
+ *   rel === '..foo'                    → INSIDE (child whose name
+ *                                        starts with `..`)
+ *
+ * Used in: walker.ts `buildExclusionState` (realRootPath outside-repo
+ * check + untracked subtree filter) and privacy-filter.ts
+ * `isPathAdmissible` (relative-to-realRootPath admission).
+ */
+export declare function isOutsideRoot(rel: string): boolean;
+/**
+ * Static secret-file deny-list. Matches `.env`, `.env.*`, `.aws/credentials`,
+ * and assorted private-key formats. Matched against absolute-path basename
+ * and a few suffix patterns. Per §4.3 step 2 first match.
+ */
+export declare const SECRET_DENY_LIST: readonly string[];
+/**
+ * Pure path test — returns true if `absolutePath` matches any secret
+ * deny-list pattern. The walker uses this to skip secret files silently
+ * (no counter increment per §4.3 hard-caps audit-quality note).
+ */
+export declare function matchesSecretDenyList(absolutePath: string): boolean;
+/**
+ * Helper exported alongside `isPathAdmissible`: returns true if
+ * `absolutePath` is either:
+ *   (a) an exact entry in `exactPaths` — file-level gitignore match,
+ *       O(1) `Set.has(p)`; OR
+ *   (b) equal to OR a descendant of an entry in `dirPrefixes` —
+ *       directory-level gitignore match, implemented via check-then-step
+ *       ancestor-walk:
+ *
+ *       let p = absolutePath;
+ *       while (true) {
+ *         if (dirPrefixes.has(p)) return true;
+ *         const parent = path.dirname(p);
+ *         if (parent === p) return false;   // filesystem root reached
+ *         p = parent;
+ *       }
+ *
+ * Key properties (per round-7 revision Codex r6 H-1 + Gemini r6 H-1/M-2):
+ *
+ *   1. **Signature is 3-arg** `(absolutePath, exactPaths, dirPrefixes)`.
+ *      The helper does NOT receive `realRootPath`. The walk MUST proceed
+ *      past `realRootPath` because `git ls-files --directory` may report
+ *      an ignored ancestor ABOVE the launch root (e.g., parent
+ *      `.gitignore` ignores `sub/` when launch root is `repo/sub/inner`).
+ *   2. **Check-then-step semantics**: check `dirPrefixes.has(p)` BEFORE
+ *      advancing `p`. This handles the case where `absolutePath` is
+ *      itself an entry in `dirPrefixes` (e.g., Step 0.5 root admission
+ *      tests `realRootPath` directly when it is itself ignored).
+ *   3. **Loop termination**: when `path.dirname(p) === p` (POSIX `/`,
+ *      Windows `C:\`). NO early termination at `realRootPath`.
+ *
+ * Lookup cost is O(absolute filesystem depth) (typically <30 on any sane
+ * mount tree), independent of `|dirPrefixes|`.
+ */
+export declare function isPathInIgnoredPrefixes(absolutePath: string, exactPaths: Set<string>, dirPrefixes: Set<string>): boolean;
+/**
+ * INTERNAL helper (not exported from the module index, but exported here
+ * so the manifest dispatcher + README reader can import it). Returns true
+ * iff `realFile` is already accounted for in the walker's two-set ledger
+ * (exact match OR equal-to-or-descendant-of an entry in pruned prefixes).
+ *
+ * Same canonical algorithm as `isPathInIgnoredPrefixes` — 3-arg signature,
+ * check-then-step, filesystem-root termination. Per round-7 revision
+ * Gemini r6 M-1 + Codex r6 H-1 + Gemini r6 M-2.
+ */
+export declare function isPathAccountedFor(realFile: string, countedExactPaths: Set<string>, countedPrunedPrefixes: Set<string>): boolean;
+/**
+ * Order of checks (mirrors §4.3 step 2, first match wins):
+ *   1. secret (deny-list path-glob match — operates on basename + suffix).
+ *   2. untracked (`state.untrackedSet.has(absolutePath)`; SKIPPED if
+ *      notInGitRepo).
+ *   3. gitignore (`isPathInIgnoredPrefixes(...)`; SKIPPED if notInGitRepo).
+ *   4. userIgnore (`state.userIgnoreMatcher.ignores(path.relative(
+ *      realRootPath, absolutePath), isDir)`).
+ *
+ * Pure in-memory check; consults only the pre-built `state`. No I/O.
+ *
+ * `isDir` (Stage 2 r2 fix, M-2 Gemini M-1): walker passes
+ * `entry.isDirectory()` here. File-only callers (manifest dispatcher,
+ * README reader) accept the default `false`. The flag is consumed by
+ * `userIgnoreMatcher.ignores()` to honour trailing-slash `dir/` rules.
+ *
+ * Caller is responsible for incrementing the appropriate counter on
+ * `privacyEnvelope` when `admissible === false` (so audit signal is
+ * preserved). `reason === 'secret'` is silent (no counter — per §4.3
+ * hard-caps audit-quality note).
+ */
+export declare function isPathAdmissible(absolutePath: string, state: ExclusionState, isDir?: boolean): {
+    admissible: true;
+} | {
+    admissible: false;
+    reason: 'secret' | 'untracked' | 'gitignore' | 'userIgnore';
+};
+export type { ExclusionState } from './types';

package/dist/structural-summary/safe-file-read.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TOCTOU-safe text file read. Returns the file contents as UTF-8 or
+ * `null` on any refusal / error. See module JSDoc for the syscall
+ * sequence + threat model.
+ *
+ * @param absPath Absolute filesystem path. Caller is responsible for
+ *                path absolutism + admission-oracle checks BEFORE
+ *                invoking this function; this helper only guards the
+ *                lstat→open transition.
+ */
+export declare function safeReadTextFile(absPath: string): Promise<string | null>;