@adhdev/mesh-shared 1.0.82-rc.36 → 1.0.82-rc.38

package/src/release.ts

@@ -0,0 +1,121 @@
+/**
+ * release — types, limits and pure helpers for release objects
+ * (docs/design/2026-11-01-release-objects.md).
+ *
+ * A release is a mesh-scoped entity that groups MISSIONS (explicit membership) and records
+ * deploy facts. It is distinct from the vendor release stamp (a build channel stamp) and
+ * from `.adhdev/preview-deploy.json` (the per-checkout deploy record it snapshots).
+ * Membership is only ever created by an explicit call; git evaluation and deploy heads
+ * produce suggestions, never members. Dependency-free leaf.
+ */
+
+export const MESH_RELEASE_CHANNELS = ['preview', 'stable'] as const
+export type MeshReleaseChannel = typeof MESH_RELEASE_CHANNELS[number]
+export function isMeshReleaseChannel(value: unknown): value is MeshReleaseChannel {
+    return typeof value === 'string' && (MESH_RELEASE_CHANNELS as readonly string[]).includes(value)
+}
+
+export const MESH_RELEASE_STATUSES = ['planned', 'frozen', 'deployed', 'verified', 'superseded', 'cancelled'] as const
+export type ReleaseStatus = typeof MESH_RELEASE_STATUSES[number]
+export function isReleaseStatus(value: unknown): value is ReleaseStatus {
+    return typeof value === 'string' && (MESH_RELEASE_STATUSES as readonly string[]).includes(value)
+}
+
+export const RELEASE_MEMBER_STATES = ['member', 'moved_out', 'removed'] as const
+export type ReleaseMemberState = typeof RELEASE_MEMBER_STATES[number]
+
+/** Who may write release membership. The daemon never adds a member on its own. */
+export const RELEASE_ACTORS = ['coordinator', 'owner', 'assistant', 'script'] as const
+export type ReleaseActor = typeof RELEASE_ACTORS[number]
+
+export const RELEASE_EVENT_TYPES = [
+    'created', 'status_changed', 'scope_added', 'scope_moved', 'scope_removed',
+    'deploy_recorded', 'changelog_drafted', 'changelog_applied',
+] as const
+export type ReleaseEventType = typeof RELEASE_EVENT_TYPES[number]
+
+/** Mission-side events recorded when membership changes (so the mission history shows it). */
+export const MISSION_RELEASE_EVENT_TYPES = ['release_attached', 'release_moved', 'release_detached'] as const
+
+export const RELEASE_LIMITS = {
+    name: 80,
+    note: 500,
+    /** `mesh_missions.release_note`: one user/operator-visible sentence. */
+    releaseNote: 400,
+    missionsPerCall: 100,
+    changelogEntries: 300,
+} as const
+
+/** Deploy targets snapshot (a copy of `.adhdev/preview-deploy.json` `targets`). */
+export interface ReleaseDeployTarget {
+    commit?: string
+    deployedAt?: string
+    previewVersion?: string
+    [key: string]: unknown
+}
+export type ReleaseTargets = Partial<Record<'npm' | 'server' | 'web', ReleaseDeployTarget>> & Record<string, ReleaseDeployTarget | undefined>
+
+export const CHANGELOG_SECTIONS = ['Added', 'Fixed', 'Changed'] as const
+export type ChangelogSection = typeof CHANGELOG_SECTIONS[number]
+
+export interface ChangelogDraftEntry {
+    missionId: string
+    /** `<!-- m:<id8> -->` — the idempotency marker `--apply` writes after the line. */
+    marker: string
+    section: ChangelogSection
+    /** The sentence that would be written to CHANGELOG.md. */
+    text: string
+    source: 'release_note' | 'summary'
+    /** True when `text` is not user-facing wording yet (carries the needs-wording marker). */
+    needsWording?: boolean
+    /** Evidence kept in the draft JSON only; never written to CHANGELOG.md. */
+    evidence?: { gitState?: string; outcome?: string; shas?: string[] }
+    /** Non-blocking lint warnings (internal ids / wave numbers / forbidden phrases). */
+    lint?: string[]
+}
+
+export interface ChangelogDraftExcluded {
+    missionId: string
+    reason: string
+}
+
+export interface ChangelogDraft {
+    generatedAt: string
+    entries: ChangelogDraftEntry[]
+    /** Member missions without a `release_note` (target 0 at deploy time). */
+    needsNote: string[]
+    excluded: ChangelogDraftExcluded[]
+    /** Member missions whose refs are not confirmed on the default branch (`not_landed` / `unknown`). */
+    warnings: Array<{ missionId: string; gitState: string; message: string }>
+    appliedAt?: string
+}
+
+export const NEEDS_WORDING_MARKER = '[needs user-facing wording]'
+
+/** Marker that makes `--apply` idempotent: one per mission entry inside CHANGELOG.md. */
+export function changelogMissionMarker(missionId: string): string {
+    return `<!-- m:${missionId.slice(0, 8)} -->`
+}
+
+/** Default section for an entry; `[Fixed]`/`[Added]`/`[Changed]` prefixes on the note pin it. */
+export function classifyChangelogSection(text: string, hint?: string): { section: ChangelogSection; text: string } {
+    const m = /^\s*\[(added|fixed|changed)\]\s*/i.exec(text)
+    if (m) {
+        const key = m[1].toLowerCase()
+        return { section: key === 'added' ? 'Added' : key === 'fixed' ? 'Fixed' : 'Changed', text: text.slice(m[0].length).trim() }
+    }
+    const probe = `${hint ?? ''} ${text}`.toLowerCase()
+    if (/\b(fix|fixes|fixed|bug|regression|crash|error)\b|오류|결함|버그|수정/.test(probe)) return { section: 'Fixed', text }
+    if (/\b(add|adds|added|new|introduc\w*|support\w*)\b|신규|추가/.test(probe)) return { section: 'Added', text }
+    return { section: 'Changed', text }
+}
+
+/** Phrases that must not reach a public CHANGELOG (internal waves, rc numbering, ids). Warning-only. */
+export function lintChangelogText(text: string): string[] {
+    const out: string[] = []
+    if (/\bwave[\s-]*\d+/i.test(text) || /웨이브\s*\d+/.test(text)) out.push('mentions an internal wave number')
+    if (/\brc[.\s-]?\d+\b/i.test(text)) out.push('mentions an internal rc number')
+    if (/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i.test(text) || /\bmi_[0-9a-f]{12}\b/.test(text) || /\brel_[0-9a-f]{12}\b/.test(text)) out.push('contains an internal id')
+    if (/\bmission\b/i.test(text)) out.push('mentions "mission" (internal vocabulary)')
+    return out
+}

package/src/turn-ipc-mission.ts

@@ -94,6 +94,8 @@ export interface MissionUpsertRequest {
      */
     structured?: boolean
     summary?: string
+    /** One user/operator-visible sentence for the release CHANGELOG draft (design 2026-11-01-release-objects L5). `''` clears. */
+    releaseNote?: string
     outcome?: string
     outcomeReason?: string
     /** Mission id open items move to when this call closes the mission (default: the carry-over mission). */
@@ -114,6 +116,7 @@ export interface MeshMissionOpenItemCountsWire {
 /** Structured-missions fields (only with `structured: true` on the request). */
 export interface MeshMissionStructuredWire {
     summary?: string
+    releaseNote?: string
     outcome?: string
     outcomeReason?: string
     version?: number
@@ -137,7 +140,7 @@ export interface MissionUpsertResponse {
     result?: Record<string, unknown>
 }
 
-const STRUCTURED_MISSION_KEYS = ['summary', 'outcome', 'outcomeReason', 'version', 'carryOver', 'openItems'] as const
+const STRUCTURED_MISSION_KEYS = ['summary', 'releaseNote', 'outcome', 'outcomeReason', 'version', 'carryOver', 'openItems'] as const
 
 function isOpenItemCountsWire(value: unknown): value is MeshMissionOpenItemCountsWire {
     if (!isRecord(value) || !hasOnlyKeys(value, ['remaining', 'live_check', 'decision', 'evidence'])) return false
@@ -145,7 +148,7 @@ function isOpenItemCountsWire(value: unknown): value is MeshMissionOpenItemCount
 }
 
 function isStructuredMissionFields(value: Record<string, unknown>): boolean {
-    for (const k of ['summary', 'outcome', 'outcomeReason'] as const) {
+    for (const k of ['summary', 'releaseNote', 'outcome', 'outcomeReason'] as const) {
         if (value[k] !== undefined && typeof value[k] !== 'string') return false
     }
     if (value.version !== undefined && !isNonNegativeInt(value.version)) return false
@@ -165,7 +168,7 @@ function isMeshMissionRecordWire(value: unknown): value is MeshMissionRecordWire
 }
 
 function isMissionUpsertRequest(value: unknown): value is MissionUpsertRequest {
-    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'id', 'title', 'goal', 'status', 'brief', 'structured', 'summary', 'outcome', 'outcomeReason', 'carryOverTo', 'toCarryOver', 'itemsAdd', 'itemsUpdate'])) return false
+    if (!isRecord(value) || !hasOnlyKeys(value, ['v', 'meshId', 'id', 'title', 'goal', 'status', 'brief', 'structured', 'summary', 'releaseNote', 'outcome', 'outcomeReason', 'carryOverTo', 'toCarryOver', 'itemsAdd', 'itemsUpdate'])) return false
     if (value.v !== TURN_IPC_PROTOCOL_VERSION) return false
     if (!isEvidenceIdentifier(value.meshId)) return false
     if (value.id !== undefined && !isEvidenceIdentifier(value.id)) return false
@@ -174,7 +177,7 @@ function isMissionUpsertRequest(value: unknown): value is MissionUpsertRequest {
     if (value.title.trim().length === 0 && value.toCarryOver !== true && value.id === undefined) return false
     if (value.structured !== undefined && typeof value.structured !== 'boolean') return false
     if (value.toCarryOver !== undefined && typeof value.toCarryOver !== 'boolean') return false
-    for (const k of ['summary', 'outcome', 'outcomeReason'] as const) {
+    for (const k of ['summary', 'releaseNote', 'outcome', 'outcomeReason'] as const) {
         if (value[k] !== undefined && typeof value[k] !== 'string') return false
     }
     if (value.carryOverTo !== undefined && !isEvidenceIdentifier(value.carryOverTo)) return false
@@ -324,6 +327,7 @@ export interface MissionListSummaryVerboseWire {
     closeCandidateEmittedAt?: string | null
     /** Structured lists only. */
     summary?: string
+    releaseNote?: string
     outcome?: string
     outcomeReason?: string
     version?: number
@@ -351,6 +355,7 @@ export interface MissionListSummarySlimWire {
     closeCandidateEmittedAt?: string | null
     /** Structured lists only. */
     summary?: string
+    releaseNote?: string
     outcome?: string
     outcomeReason?: string
     version?: number