@adhdev/mesh-shared 0.9.82-rc.267

package/src/git-normalize.ts

@@ -0,0 +1,176 @@
+/**
+ * Canonical git-status normalizers shared by the cloud (web-core) and standalone
+ * (daemon-core router) mesh paths. Previously each transport hand-maintained its
+ * own copy and they drifted (e.g. submodule drop rules, evidence checks); this is
+ * the one implementation both import.
+ */
+
+import { joinRepoPath, readBoolean, readNumber, readRecord, readString, type JsonRecord } from './json'
+import type { GitRepoStatus, GitSubmoduleStatus, GitUpstreamFreshness } from './types'
+
+export function scoreGitUpstreamFreshness(status: GitUpstreamFreshness | undefined): number {
+    switch (status) {
+        case 'fresh':
+            return 30
+        case 'no_upstream':
+            return 4
+        case 'unchecked':
+        case undefined:
+            return 0
+        case 'stale':
+            return -10
+        case 'unavailable':
+            return -15
+        default:
+            return 0
+    }
+}
+
+export function readGitSubmodules(value: unknown, parentRepoRoot?: string): GitSubmoduleStatus[] | undefined {
+    if (!Array.isArray(value)) return undefined
+    const submodules = value
+        .map(entry => {
+            const submodule = readRecord(entry)
+            const path = readString(submodule.path)
+            const commit = readString(submodule.commit)
+            const repoPath = readString(submodule.repoPath, submodule.repo_root)
+                ?? joinRepoPath(parentRepoRoot, path)
+            // repoPath is only used for the submodule node's display workspace, which is
+            // allowed to be empty. The cloud P2P transit path can deliver submodule entries
+            // without repoPath (and a per-node git object without a derivable repoRoot), so
+            // dropping on missing repoPath would silently strip every submodule graph node.
+            // Keep any submodule that carries both path and commit.
+            if (!path || !commit) return null
+            const result: GitSubmoduleStatus = {
+                path,
+                commit,
+                dirty: readBoolean(submodule.dirty) ?? false,
+                outOfSync: readBoolean(submodule.outOfSync, submodule.out_of_sync) ?? false,
+                lastCheckedAt: readNumber(submodule.lastCheckedAt, submodule.last_checked_at) ?? Date.now(),
+            }
+            if (repoPath) result.repoPath = repoPath
+            const error = readString(submodule.error)
+            if (error) result.error = error
+            return result
+        })
+        .filter((entry): entry is GitSubmoduleStatus => entry !== null)
+    return submodules.length > 0 ? submodules : undefined
+}
+
+export function hasGitStatusEvidence(status: JsonRecord): boolean {
+    // BUG FIX: a transit-reshaped git status that carries only a repoRoot/workspace
+    // (e.g. cloud P2P stripped the branch/upstream/counters but kept the path) must
+    // NOT be dropped — otherwise the node loses its git object and any submodules
+    // hanging off it. Treat a present repoRoot/repo_root/workspace as evidence too.
+    return readBoolean(status.isGitRepo) !== undefined
+        || Boolean(readString(status.branch, status.upstream, status.upstreamStatus, status.upstream_status, status.headCommit))
+        || Boolean(readString(status.repoRoot, status.repo_root, status.workspace))
+        || readNumber(
+            status.ahead,
+            status.behind,
+            status.staged,
+            status.modified,
+            status.untracked,
+            status.deleted,
+            status.renamed,
+            status.lastCheckedAt,
+            status.last_checked_at,
+        ) !== undefined
+        || (Array.isArray(status.submodules) && status.submodules.length > 0)
+}
+
+export function normalizeGitStatus(
+    status: JsonRecord,
+    node: JsonRecord,
+    options?: { lastCheckedAt?: number },
+): GitRepoStatus | undefined {
+    const explicitIsGitRepo = readBoolean(status.isGitRepo)
+    if (!Object.keys(status).length || !hasGitStatusEvidence(status)) return undefined
+    const isGitRepo = explicitIsGitRepo ?? true
+    const conflictFiles = Array.isArray(status.conflictFiles)
+        ? status.conflictFiles.filter((entry): entry is string => typeof entry === 'string')
+        : []
+    const conflictCount = readNumber(status.conflicts) ?? conflictFiles.length
+    const hasConflicts = readBoolean(status.hasConflicts) ?? conflictCount > 0
+    // node.workspace is in the fallback chain so a transit node carrying its path only
+    // on the node (not the inner git object) still yields a parentRepoRoot for submodules.
+    const repoRoot = readString(status.repoRoot, status.repo_root, node.repoRoot, node.repo_root, status.workspace, node.workspace) || undefined
+    const submodules = readGitSubmodules(status.submodules, repoRoot)
+    const upstreamStatus = readString(status.upstreamStatus, status.upstream_status)
+    const upstreamFetchedAt = readNumber(status.upstreamFetchedAt, status.upstream_fetched_at)
+    const upstreamFetchError = readString(status.upstreamFetchError, status.upstream_fetch_error)
+    const error = readString(status.error)
+    const staged = readNumber(status.staged) ?? 0
+    const modified = readNumber(status.modified) ?? 0
+    const untracked = readNumber(status.untracked) ?? 0
+    const deleted = readNumber(status.deleted) ?? 0
+    const renamed = readNumber(status.renamed) ?? 0
+    return {
+        workspace: readString(status.workspace, node.workspace) || '',
+        repoRoot: repoRoot ?? null,
+        isGitRepo,
+        branch: readString(status.branch) ?? null,
+        headCommit: readString(status.headCommit) ?? null,
+        headMessage: readString(status.headMessage) ?? null,
+        upstream: readString(status.upstream) ?? null,
+        upstreamStatus: (upstreamStatus as GitUpstreamFreshness) ?? 'unchecked',
+        ...(upstreamFetchedAt !== undefined ? { upstreamFetchedAt } : {}),
+        ...(upstreamFetchError ? { upstreamFetchError } : {}),
+        ahead: readNumber(status.ahead) ?? 0,
+        behind: readNumber(status.behind) ?? 0,
+        staged,
+        modified,
+        untracked,
+        deleted,
+        renamed,
+        dirty: readBoolean(status.dirty, status.isDirty, status.is_dirty) ?? (staged + modified + untracked + deleted + renamed > 0 || hasConflicts),
+        hasConflicts,
+        conflictFiles,
+        stashCount: readNumber(status.stashCount, status.stash_count) ?? 0,
+        lastCheckedAt: options?.lastCheckedAt ?? readNumber(status.lastCheckedAt, status.last_checked_at) ?? Date.now(),
+        ...(submodules ? { submodules } : {}),
+        ...(error ? { error } : {}),
+    }
+}
+
+export function scoreGitStatusCandidate(git: GitRepoStatus | undefined): number {
+    if (!git) return Number.NEGATIVE_INFINITY
+    let score = 0
+    if (git.isGitRepo === true) score += 50
+    if (git.isGitRepo === false) score -= 10
+    if (git.branch) score += 20
+    if (git.headCommit) score += 20
+    if (git.upstream) score += 10
+    score += scoreGitUpstreamFreshness(git.upstreamStatus)
+    if (typeof git.ahead === 'number') score += 2
+    if (typeof git.behind === 'number') score += 2
+    if (Array.isArray(git.submodules) && git.submodules.length > 0) score += 4 + git.submodules.length
+    if (git.error) score -= 20
+    return score
+}
+
+/**
+ * Pick the best git status out of the four transit envelope slots a mesh node can
+ * carry: lastGit.status, lastGit.result.status, lastProbe.git.status,
+ * lastProbe.git.result.status. Returns undefined when none carry git evidence.
+ */
+export function pickBestTransitGitStatus(node: JsonRecord, options?: { lastCheckedAt?: number }): GitRepoStatus | undefined {
+    const rawGit = readRecord(node.lastGit ?? node.last_git)
+    const gitResult = readRecord(rawGit.result)
+    const directStatus = readRecord(rawGit.status)
+    const nestedStatus = readRecord(gitResult.status)
+    const rawProbe = readRecord(node.lastProbe ?? node.last_probe)
+    const probeGit = readRecord(rawProbe.git)
+    const probeGitResult = readRecord(probeGit.result)
+    const probeDirectStatus = readRecord(probeGit.status)
+    const probeNestedStatus = readRecord(probeGitResult.status)
+    const lastCheckedAt = options?.lastCheckedAt
+    let best: { git: GitRepoStatus; score: number } | null = null
+    for (const status of [directStatus, nestedStatus, probeDirectStatus, probeNestedStatus]) {
+        const normalized = normalizeGitStatus(status, node, { lastCheckedAt: lastCheckedAt ?? Date.now() })
+        if (!normalized) continue
+        const score = scoreGitStatusCandidate(normalized)
+        if (!best || score > best.score) best = { git: normalized, score }
+    }
+    return best?.git
+}

package/src/git-summarize.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical compact git-shape summarizer used by debug/log surfaces on both the
+ * cloud (daemon-cloud mesh command summarizer) and standalone (daemon-core router
+ * RepoMeshStatusDebug) paths. Produces a small, log-safe projection of a git
+ * status record — commit SHAs are truncated to 12 chars.
+ *
+ * Transport-specific envelope unwrapping (result / result.status / top-level)
+ * stays in the caller; this takes an already-unwrapped status record.
+ */
+
+import { readBoolean, readNumber, readRecord, readString } from './json'
+
+export function summarizeGitShape(status: unknown): Record<string, unknown> | null {
+    const record = readRecord(status)
+    if (!Object.keys(record).length) return null
+    const submodules = Array.isArray(record.submodules)
+        ? record.submodules.map((entry: unknown) => {
+            const sub = readRecord(entry)
+            return {
+                path: readString(sub.path) ?? null,
+                commit: readString(sub.commit)?.slice(0, 12) ?? null,
+                dirty: readBoolean(sub.dirty) ?? false,
+                outOfSync: readBoolean(sub.outOfSync, sub.out_of_sync) ?? false,
+            }
+        })
+        : []
+    return {
+        isGitRepo: readBoolean(record.isGitRepo),
+        workspace: readString(record.workspace) ?? null,
+        repoRoot: readString(record.repoRoot, record.repo_root) ?? null,
+        branch: readString(record.branch) ?? null,
+        upstream: readString(record.upstream) ?? null,
+        upstreamStatus: readString(record.upstreamStatus, record.upstream_status) ?? null,
+        headCommit: readString(record.headCommit, record.head_commit)?.slice(0, 12) ?? null,
+        ahead: readNumber(record.ahead) ?? null,
+        behind: readNumber(record.behind) ?? null,
+        dirtyCounts: {
+            staged: readNumber(record.staged) ?? 0,
+            modified: readNumber(record.modified) ?? 0,
+            untracked: readNumber(record.untracked) ?? 0,
+            deleted: readNumber(record.deleted) ?? 0,
+            renamed: readNumber(record.renamed) ?? 0,
+        },
+        lastCheckedAt: readNumber(record.lastCheckedAt, record.last_checked_at) ?? null,
+        submoduleCount: submodules.length,
+        submodules,
+    }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @adhdev/mesh-shared — pure, dependency-free mesh/git status normalizers shared
+ * by daemon-core (standalone / local IPC) and web-core (cloud / P2P transit).
+ *
+ * This package exists to kill a recurring bug class: the cloud and standalone
+ * transports each used to carry their own hand-synced copy of these normalizers,
+ * and they drifted (cloud would strip/reshape fields, the web filter would drop
+ * entries the standalone path kept). Both cores now import this single source of
+ * truth. It MUST stay a pure leaf — types + pure functions on plain JS objects,
+ * no Node/DOM APIs, no git exec, no transport, and an empty dependency set.
+ */
+
+export * from './json'
+export * from './types'
+export * from './git-normalize'
+export * from './session-normalize'
+export * from './git-summarize'

package/src/json.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure JSON-record reading primitives shared by the cloud (web-core / P2P transit)
+ * and standalone (daemon-core / local IPC) mesh normalizers.
+ *
+ * These operate only on plain JS values — no Node/DOM APIs, no transport, no git
+ * exec — so both cores can import them without violating the core↔core dependency
+ * ban. They are the single source of truth for the field-coercion rules that the
+ * two transports previously hand-synced (and drifted on).
+ */
+
+export type JsonRecord = Record<string, unknown>
+
+export function readRecord(value: unknown): JsonRecord {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : {}
+}
+
+export function readString(...values: unknown[]): string | undefined {
+    for (const value of values) {
+        if (typeof value !== 'string') continue
+        const trimmed = value.trim()
+        if (trimmed) return trimmed
+    }
+    return undefined
+}
+
+export function readNumber(...values: unknown[]): number | undefined {
+    for (const value of values) {
+        if (typeof value === 'number' && Number.isFinite(value)) return value
+    }
+    return undefined
+}
+
+export function readBoolean(...values: unknown[]): boolean | undefined {
+    for (const value of values) {
+        if (typeof value === 'boolean') return value
+    }
+    return undefined
+}
+
+export function readStringArray(value: unknown): string[] {
+    return Array.isArray(value)
+        ? value.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0)
+        : []
+}
+
+/**
+ * Join a (possibly absent) repo root with a relative submodule path. Returns the
+ * path unchanged when it is already absolute, and undefined when nothing usable
+ * can be derived — callers must treat the result as optional.
+ */
+export function joinRepoPath(root: string | undefined, relativePath: string | undefined): string | undefined {
+    const normalizedRoot = typeof root === 'string' ? root.trim().replace(/[\\/]+$/, '') : ''
+    const normalizedPath = typeof relativePath === 'string' ? relativePath.trim() : ''
+    if (!normalizedPath) return undefined
+    if (/^(?:[A-Za-z]:[\\/]|\/)/.test(normalizedPath)) return normalizedPath
+    if (!normalizedRoot) return undefined
+    return `${normalizedRoot}/${normalizedPath.replace(/^[\\/]+/, '')}`
+}

package/src/session-normalize.ts

@@ -0,0 +1,59 @@
+/**
+ * Canonical mesh-session record normalizer shared by the cloud (web-core) mesh
+ * paths. Parses an already-transit-shaped session record into a typed
+ * RepoMeshSessionStatus.
+ */
+
+import { readBoolean, readRecord, readString } from './json'
+import type { RepoMeshSessionStatus } from './types'
+
+/**
+ * Build a deterministic synthetic session id from a record that has no explicit
+ * id. Two transit refreshes of the same logical session produce the same id so
+ * downstream dedupe stays stable across refreshes (a random id would create a new
+ * node every poll). Derived from the stable identifying fields available on the
+ * record; prefixed "synthetic:" so callers can tell it apart from a real id.
+ */
+function deriveSyntheticSessionId(record: ReturnType<typeof readRecord>): string | undefined {
+    const parts = [
+        readString(record.workspace),
+        readString(record.providerType, record.provider),
+        readString(record.role),
+        readString(record.state, record.status),
+        readString(record.title),
+        readString(record.createdAt, record.created_at),
+        readString(record.startedAt, record.started_at),
+    ].filter((part): part is string => Boolean(part))
+    if (parts.length === 0) return undefined
+    return `synthetic:${parts.join('|')}`
+}
+
+export function normalizeMeshSessionRecord(entry: unknown): RepoMeshSessionStatus | null {
+    const record = readRecord(entry)
+    // BUG FIX: cloud transit can reshape/strip the explicit id field. Fall back
+    // through sessionId → session_id → id, then to a DETERMINISTIC synthetic id
+    // derived from record content so the session survives the round trip instead
+    // of being dropped (and so dedupe stays stable across refreshes). Return null
+    // ONLY when the record carries no identifying fields at all.
+    const sessionId = readString(record.sessionId, record.session_id, record.id)
+        ?? deriveSyntheticSessionId(record)
+    if (!sessionId) return null
+    return {
+        sessionId,
+        ...(readString(record.providerType, record.provider) ? { providerType: readString(record.providerType, record.provider) } : {}),
+        ...(readString(record.state, record.status) ? { state: readString(record.state, record.status) } : {}),
+        ...(readString(record.chatStatus, record.chat_status) ? { chatStatus: readString(record.chatStatus, record.chat_status) } : {}),
+        ...(readString(record.lifecycle) ? { lifecycle: readString(record.lifecycle) as RepoMeshSessionStatus['lifecycle'] } : {}),
+        ...(readString(record.surfaceKind, record.surface_kind) ? { surfaceKind: readString(record.surfaceKind, record.surface_kind) as RepoMeshSessionStatus['surfaceKind'] } : {}),
+        ...(readString(record.recoveryState, record.recovery_state) ? { recoveryState: readString(record.recoveryState, record.recovery_state) } : {}),
+        ...(readString(record.workspace) ? { workspace: readString(record.workspace) } : {}),
+        ...(readString(record.title) ? { title: readString(record.title) } : {}),
+        ...(readString(record.role) ? { role: readString(record.role) } : {}),
+        ...(readBoolean(record.isSelfCoordinator, record.is_self_coordinator) !== undefined ? { isSelfCoordinator: readBoolean(record.isSelfCoordinator, record.is_self_coordinator) } : {}),
+        ...(readString(record.statusNote, record.status_note) ? { statusNote: readString(record.statusNote, record.status_note) } : {}),
+        ...(readString(record.createdAt, record.created_at) ? { createdAt: readString(record.createdAt, record.created_at) } : {}),
+        ...(readString(record.startedAt, record.started_at) ? { startedAt: readString(record.startedAt, record.started_at) } : {}),
+        ...(readString(record.lastActivityAt, record.last_activity_at) ? { lastActivityAt: readString(record.lastActivityAt, record.last_activity_at) } : {}),
+        ...(readBoolean(record.isCached, record.is_cached) !== undefined ? { isCached: readBoolean(record.isCached, record.is_cached) } : {}),
+    }
+}

package/src/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Canonical pure-shape mesh/git status types.
+ *
+ * These are the single source of truth for the data shapes that cross the
+ * cloud (P2P/transit) and standalone (local IPC) boundaries. daemon-core and
+ * web-core re-export these so neither side can drift its own copy. Pure type
+ * declarations only — no runtime, no dependency on either core.
+ */
+
+export type GitUpstreamFreshness = 'fresh' | 'unchecked' | 'stale' | 'no_upstream' | 'unavailable'
+
+export type GitFailureReason =
+    | 'not_git_repo'
+    | 'git_not_installed'
+    | 'timeout'
+    | 'path_outside_repo'
+    | 'dirty_index_required'
+    | 'conflict'
+    | 'invalid_args'
+    | 'nothing_to_commit'
+    | 'git_command_failed'
+
+export interface GitRepoIdentity {
+    workspace: string
+    repoRoot: string | null
+    isGitRepo: boolean
+}
+
+export interface GitSubmoduleStatus {
+    /** Submodule path relative to repo root */
+    path: string
+    /** Current commit SHA the submodule is at */
+    commit: string
+    /**
+     * Path to the submodule repo (absolute). Optional: cloud P2P transit can
+     * deliver submodule entries without a derivable repo path, and graph
+     * rendering only uses this for a display field that is allowed to be empty.
+     */
+    repoPath?: string
+    /** Whether the submodule has uncommitted changes */
+    dirty: boolean
+    /** Whether the submodule commit differs from what the parent repo expects */
+    outOfSync: boolean
+    /** Last checked timestamp */
+    lastCheckedAt: number
+    /** Error message if submodule status could not be read */
+    error?: string
+}
+
+export interface DaemonBuildBehind {
+    /** Full build commit baked into the running daemon. */
+    buildCommit: string
+    /** Short build commit. */
+    buildCommitShort: string
+    /** HEAD commit the build commit is behind (repo or submodule). */
+    head: string
+    /** Where the comparison matched: 'root' or the submodule path. */
+    scope: string
+    /**
+     * Whether any package changed between buildCommit..HEAD affects the daemon
+     * runtime (daemon-core, standalone, session-host, terminal-mux, ghostty,
+     * mcp-server). When false, only web/render packages changed — the daemon does
+     * NOT need a rebuild/restart; only the web deploy is pending. Conservative:
+     * when the changed-package set can't be determined it defaults to true.
+     */
+    isDaemonAffecting: boolean
+    /** Distinct package names changed between buildCommit..HEAD (best-effort). */
+    affectedPackages?: string[]
+    warning: string
+}
+
+export interface GitRepoStatus extends GitRepoIdentity {
+    branch: string | null
+    headCommit: string | null
+    headMessage: string | null
+    upstream: string | null
+    /** Whether ahead/behind was verified against a freshly fetched upstream ref. */
+    upstreamStatus: GitUpstreamFreshness
+    /** Timestamp for the fetch that refreshed upstream refs when upstreamStatus === 'fresh'. */
+    upstreamFetchedAt?: number
+    /** Error from the last refresh attempt when upstreamStatus === 'stale'. */
+    upstreamFetchError?: string
+    ahead: number
+    behind: number
+    staged: number
+    modified: number
+    untracked: number
+    deleted: number
+    renamed: number
+    /** Aggregate dirty flag including root worktree changes, conflicts, stash, and submodule drift. */
+    dirty: boolean
+    hasConflicts: boolean
+    conflictFiles: string[]
+    stashCount: number
+    lastCheckedAt: number
+    /** Submodule statuses when auto-discover is enabled */
+    submodules?: GitSubmoduleStatus[]
+    /**
+     * Set when the running daemon's build commit is a STRICT ancestor of this
+     * repo's HEAD (or a submodule HEAD) — i.e. the live daemon predates committed
+     * code in this workspace and is awaiting a deploy/restart to catch up.
+     * Omitted entirely when no staleness is provable.
+     */
+    daemonBuildBehind?: DaemonBuildBehind
+    error?: string
+    reason?: GitFailureReason
+}
+
+export interface RepoMeshSessionStatus {
+    sessionId: string
+    providerType?: string
+    state?: string
+    chatStatus?: string
+    lifecycle?: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'interrupted'
+    surfaceKind?: 'live_runtime' | 'recovery_snapshot' | 'inactive_record'
+    recoveryState?: string | null
+    workspace?: string | null
+    title?: string | null
+    role?: string | null
+    isSelfCoordinator?: boolean
+    statusNote?: string | null
+    createdAt?: string | null
+    startedAt?: string | null
+    lastActivityAt?: string | null
+    isCached?: boolean
+}