@productbrain/cli 0.1.0-beta.15 → 0.1.0-beta.1502

package/dist/commands/handshake.d.ts

@@ -1,7 +1,99 @@
 /**
  * pb handshake — generate context files for AI developer tools.
- * The fourth delivery surface: context export (GLO-63, DEC-161).
+ * Context export wiring (read-only filesystem bridge; GLO-63, DEC-161) — not a product surface.
  */
+import { type HandshakeReport } from '../formatters/handshake.js';
+import type { WorkspaceHealthResult } from './workspace.js';
+import { type StartupResolutionSignals } from '../lib/startup-resolution-signals.js';
+/**
+ * Wire-safe alias for a single health gap.
+ * Derived from the CLI mirror in workspace.ts — no convex/ import needed.
+ */
+export type HealthGap = WorkspaceHealthResult['gaps'][number];
+/**
+ * Structured result returned by probeStarterSetupSeeded when seeds are still
+ * pending or when the health query is unavailable.
+ */
+export type SeedsPendingResult = {
+    status: 'seeds-pending';
+    gaps: ReadonlyArray<HealthGap>;
+} | {
+    status: 'seeds-ready';
+} | {
+    status: 'probe-failed';
+    error: string;
+};
+/**
+ * DORMANT_MARKER — appended to previously-projected asset files when the asset's
+ * gate deactivates (e.g. workspace readiness exceeds the max threshold).
+ *
+ * Contract:
+ *   - The file is NOT deleted. It persists on disk so that history is preserved
+ *     and the agent surface remains inspectable.
+ *   - The marker is appended at the end of the file, idempotent — if it already
+ *     exists, no second append occurs.
+ *   - The marker does NOT trigger a drift TEN. Dormant files are intentionally
+ *     deactivated, not accidentally forked.
+ *   - The marker is never included in active file writes — only dormant writes.
+ *
+ * Used by: writeDormantMarker() (write) and hasDormantMarker() (idempotency check).
+ * Exported for use in tests.
+ *
+ * Chain: WP-379 S4.
+ */
+export declare const DORMANT_MARKER = "<!-- pb-status: dormant -->";
+/**
+ * writeDormantMarker — append the dormant marker to a previously-projected file.
+ *
+ * Idempotent: if DORMANT_MARKER is already present, no-op.
+ * Only operates on files that have the auto-gen MARKER — we never touch
+ * manually-authored files.
+ *
+ * @param filePath  Absolute path to the file.
+ * @returns         'written' | 'already-dormant' | 'skipped' (no auto-gen marker)
+ */
+export declare function writeDormantMarkerToFile(filePath: string): 'written' | 'already-dormant' | 'skipped';
+/**
+ * renameSurfaceForDormancy — rename a projected surface file to `<path>.dormant`
+ * so external scanners (which glob *.md / *.mdc) stop loading it. WP-426 E4.
+ * The HTML-comment marker is invisible to scanners; the extension change removes
+ * the file from their glob set. Only touches files carrying the auto-gen MARKER.
+ * Runs on an INDEPENDENT existence check (not gated on marker-write result) so
+ * legacy WP-379 marker-only files still rename. Idempotent.
+ * Codex P1: when a .dormant already exists, only replace it if its body matches the
+ * live file. A divergent .dormant (user edited it) is preserved and reported as 'drift'
+ * rather than force-deleted — no silent data loss.
+ * @returns 'renamed' | 'replaced' | 'already-dormant' | 'skipped' | 'drift'
+ */
+export declare function renameSurfaceForDormancy(filePath: string): 'renamed' | 'replaced' | 'already-dormant' | 'skipped' | 'drift';
+/**
+ * restoreSurfaceFromDormant — clean the orphan `<path>.dormant` sibling after a
+ * raised (observe→project) asset has been re-projected fresh from the DB body by
+ * the normal write loop. WP-426 E4.
+ * Normalizes the volatile auto-gen timestamp (via normalizeHandshakeContentForComparison)
+ * before comparing, else the lowering-time timestamp would always force a false
+ * 'orphan-drift'. Identical body → remove. Differs (user edited) → preserve + drift.
+ * @returns 'restored' | 'orphan-drift' | 'skipped'
+ */
+export declare function restoreSurfaceFromDormant(filePath: string): 'restored' | 'orphan-drift' | 'skipped';
+/**
+ * Single-shot health probe — calls `workspace.health` and inspects
+ * `starterSetupSeeded`. Does NOT poll internally; polling is the caller's
+ * responsibility (connect-context.ts).
+ *
+ * Returns:
+ *  - `seeds-ready`   — health query succeeded AND starterSetupSeeded is true
+ *  - `seeds-pending` — health query succeeded but starterSetupSeeded is false
+ *  - `probe-failed`  — health query threw (network, auth, etc.)
+ */
+export declare function probeStarterSetupSeeded(): Promise<SeedsPendingResult>;
+/**
+ * Poll `probeStarterSetupSeeded` up to MAX_POLLS times (10s at 500ms intervals).
+ * Returns the final probe result — caller decides how to render the outcome.
+ *
+ * Exported so connect-context.ts can use it without re-implementing the loop.
+ */
+export declare function pollUntilSeedsReady(): Promise<SeedsPendingResult>;
 export declare function runHandshakeInit(options?: {
     level?: string;
     dryRun?: boolean;
@@ -9,10 +101,149 @@ export declare function runHandshakeInit(options?: {
 interface HandshakeOptions {
     force?: boolean;
     dryRun?: boolean;
+    /** When true, actually write files. When false (default), show preview plan only. */
+    apply?: boolean;
     level?: string;
     /** When true, suppress all progress output. Used when handshake is called as a sub-step. */
     quiet?: boolean;
+    /** When true, fetch governance entries from the Chain and merge generated rules. */
+    generate?: boolean;
+    /** Optional caller-provided startup signals, merged with safe local signals. */
+    startupSignals?: Partial<StartupResolutionSignals>;
+    /** Queryable telemetry attribution for the path that invoked this handshake. */
+    invocationPath?: 'session-start' | 'session-close' | 'manual-orient' | 'handshake' | 'unknown';
+    /** Target surfaces to write adapter files for. Empty = write all. */
+    surfaces?: string[];
+    /**
+     * WP-421 S3 (doneWhen #17): when true, OR when stdout is not a TTY, the
+     * tampered-bucket adopt-or-revert prompt is bypassed. Tampered files are
+     * enumerated to stderr, a kind='transition' setup_receipt row records the
+     * refusal, and the process exits non-zero. Never silently sync.
+     */
+    noPrompt?: boolean;
+    /**
+     * WP-439 S4: opt out of strict body-fetch mode. By default any
+     * fetchAssetBody failure makes the handshake exit non-zero with an actionable
+     * pointer at `pb setup-audit --repair`. When --lenient is passed, failures
+     * become non-fatal warnings (the legacy behaviour) and projection continues
+     * with the affected entries skipped.
+     */
+    lenient?: boolean;
 }
-export declare function runHandshake(options?: HandshakeOptions): Promise<void>;
+/**
+ * Dereference a "PR #N" ref to its changed paths via `gh pr diff <N> --name-only`.
+ * F4 (spec "PR refs must dereference to diff paths when available"): the server
+ * resolver has no git/gh access, so PR-domain evidence can only be produced
+ * here in the CLI. Guarded: `gh` may be absent/unauthed or the PR may not exist,
+ * so failures are swallowed (returns []) and the call is time-boxed.
+ *
+ * Injectable via `run` so tests can drive the dereference without a real `gh`.
+ */
+export declare function dereferencePrRefToPaths(cwd: string, prNumber: number, run?: (cwd: string, command: string, timeoutMs: number) => string | undefined): string[];
+/**
+ * Injectable runners for deriveHandshakeStartupSignals — lets tests drive the
+ * git/gh side effects (changed paths, merge-base delta, PR-diff dereference)
+ * without real subprocesses. Production defaults call the real implementations.
+ */
+export type HandshakeStartupSignalDeps = {
+    /** Run a read-only git command; undefined on failure. Default: runGitText. */
+    runGit: (cwd: string, command: string) => string | undefined;
+    /** Dereference a PR number to its changed paths (F4). Default: dereferencePrRefToPaths. */
+    prDiff: (cwd: string, prNumber: number) => string[];
+};
+export declare function deriveHandshakeStartupSignals(cwd: string, callerSignals?: Partial<StartupResolutionSignals>, deps?: HandshakeStartupSignalDeps): StartupResolutionSignals;
+/**
+ * Normalize volatile handshake-only timestamps before comparing generated files.
+ * This keeps the visible timestamps in generated artifacts while avoiding
+ * meaningless rewrites when semantic content is unchanged.
+ */
+export declare function normalizeHandshakeContentForComparison(content: string): string;
+declare function setupAuthoringPath(cwd: string, asset: {
+    entryId: string;
+    name: string;
+    assetKind: string;
+    authoringPath?: string | null;
+}): string | null;
+type AuthoringSyncState = {
+    version: 1;
+    assets: Record<string, {
+        path: string;
+        hash: string;
+    }>;
+    dormantRenamed?: string[];
+    dormantReactivated?: string[];
+};
+declare function loadAuthoringSyncState(productbrainDir: string): AuthoringSyncState;
+export type DriftBucket = 'pb-managed-clean' | 'pb-managed-tampered' | 'user-owned';
+/**
+ * Classify a single projection-target file into one of the three drift buckets.
+ *
+ * Returns `null` when `filePath` does not exist (first-run / unprojected) — the
+ * write loop treats that as "would-write" and the file is not part of any bucket.
+ *
+ * @param filePath  Absolute path to the projection file on disk.
+ * @returns         { bucket, expectedHash, actualHash } when the file exists.
+ *                  `expectedHash`/`actualHash` are populated only for the
+ *                  tampered bucket so the headless refusal payload can include
+ *                  them verbatim. For clean / user-owned, both are `''`.
+ */
+export declare function classifyDriftBucket(filePath: string): {
+    bucket: DriftBucket;
+    expectedHash: string;
+    actualHash: string;
+} | null;
+/**
+ * Result of a single unlink decision during resolveProjectionCollision.
+ */
+type CollisionUnlinkResult = {
+    action: 'kept';
+    filePath: string;
+    reason: string;
+} | {
+    action: 'unlinked';
+    filePath: string;
+    reason: string;
+} | {
+    action: 'collision-ten';
+    filePath: string;
+    reason: string;
+};
+/**
+ * resolveProjectionCollision — WP-379 S5b
+ *
+ * Marker-scoped orphan unlink: enumerates target dirs (.cursor/rules/,
+ * .claude/rules/, .claude/skills/, .codex/skills/); for each file that has
+ * the auto-gen MARKER whose lowercase-normalized filename does NOT match any
+ * current active-asset materializedFilename, the file is unlinked.
+ *
+ * User-owned files (no MARKER) are never touched, regardless of name.
+ *
+ * Linux case-collision disambiguation:
+ *   1. Exact match (lowercase name == any canonical name): survives.
+ *   2. Case-variant with MARKER (marker file, no exact canonical match): unlinked.
+ *   3. Ambiguous (zero exact, multiple case-variants with MARKER):
+ *      newest mtime wins; all others are unlinked; a collision TEN is
+ *      appended to the session capture queue (not fired inline).
+ *
+ * Returns a list of unlink results so the caller can log/report them.
+ *
+ * @param cwd         Project root (absolute path).
+ * @param assetNames  The current set of canonical asset names from the server
+ *                    (e.g. ["Setup-ProductBrain", "chain-rules"]).
+ * @param log         Progress log function.
+ * @param logErr      Error log function.
+ */
+export declare function resolveProjectionCollision(cwd: string, assetNames: string[], log: (msg: string) => void, logErr: (msg: string) => void): {
+    results: CollisionUnlinkResult[];
+    collisionTens: string[];
+};
+export declare function runHandshake(options?: HandshakeOptions): Promise<HandshakeReport | undefined>;
+export declare const __test: {
+    setupAuthoringPath: typeof setupAuthoringPath;
+    renameSurfaceForDormancy: typeof renameSurfaceForDormancy;
+    restoreSurfaceFromDormant: typeof restoreSurfaceFromDormant;
+    loadAuthoringSyncState: typeof loadAuthoringSyncState;
+    MARKER: string;
+};
 export {};
 //# sourceMappingURL=handshake.d.ts.map

package/dist/commands/handshake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/commands/handshake.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4LH,wBAAsB,gBAAgB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CxG;AACD,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAsBD,wBAAsB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqLhF"}
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/commands/handshake.ts"],"names":[],"mappings":"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"}