@point-seven-studio/jq-crosstalk 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Pure rules over a crosstalk mailbox: what is waiting, which messages belong to
3
+ * one thread, and the state of the board. No I/O; read.ts gathers the messages.
4
+ *
5
+ * Mail sent by a current tool carries a real `thread:` id, which is used when present.
6
+ * Older or hand-written mail has none, so its threads are DERIVED, from two signals a
7
+ * sender already leaves:
8
+ * 1. the body cites another message's timestamp id;
9
+ * 2. the subject is the same once "Re:" is stripped, between the same two names.
10
+ * Both are evidence, not proof, so a derived thread is a grouping for reading,
11
+ * never something to act on.
12
+ */
13
+ export interface Message {
14
+ id: string;
15
+ filename: string;
16
+ from_session: string;
17
+ to_session: string;
18
+ subject: string | null;
19
+ /** Only needed for thread derivation; summaries never return it. */
20
+ body?: string | null;
21
+ sent_at: string | null;
22
+ acked: boolean;
23
+ /** Stamped by the tool; absent on older or hand-written mail. */
24
+ kind?: string | null;
25
+ thread_id?: string | null;
26
+ reply_to?: string | null;
27
+ /** Board fields. */
28
+ tags?: string[] | null;
29
+ expires_on?: string | null;
30
+ evidence?: string | null;
31
+ settled_by?: string | null;
32
+ }
33
+ /** The address that means "anyone". Mail to it is a board post or a reply to one. */
34
+ export declare const BOARD = "board";
35
+ export interface MessageSummary {
36
+ id: string;
37
+ filename: string;
38
+ from_session: string;
39
+ to_session: string;
40
+ subject: string | null;
41
+ sent_at: string | null;
42
+ acked: boolean;
43
+ age_days: number | null;
44
+ /** null on mail sent before kinds existed. */
45
+ kind: string | null;
46
+ }
47
+ export interface InboxWaiting {
48
+ product: string;
49
+ unread: number;
50
+ oldest_sent_at: string | null;
51
+ oldest_age_days: number | null;
52
+ items: MessageSummary[];
53
+ }
54
+ export interface WaitingBoard {
55
+ /** One sentence. Always says what was counted, so zero never reads as "failed to load". */
56
+ headline: string;
57
+ total_unread: number;
58
+ inboxes: InboxWaiting[];
59
+ }
60
+ export declare function ageDays(sentAt: string | null, now: number): number | null;
61
+ export declare function summarize(m: Message, now: number): MessageSummary;
62
+ /** Unread mail per inbox, the inbox holding the oldest message first. */
63
+ export declare function waitingBoard(messages: Message[], now: number): WaitingBoard;
64
+ /** "Re: Fwd: Checkout flow " → "checkout flow". Empty when there is no subject. */
65
+ export declare function normalizeSubject(subject: string | null): string;
66
+ /**
67
+ * Mailbox messages a body cites, as timestamp ids (`YYYYMMDD-HHMMSS`). Senders cite
68
+ * the full filename, a shortened one, or the bare stamp (`archive/x/20260817-195838`),
69
+ * and the stamp is the part all three share.
70
+ */
71
+ export declare function citedStamps(body: string | null | undefined): string[];
72
+ export interface Thread {
73
+ /** The first message's filename: stable as the thread grows. */
74
+ id: string;
75
+ subject: string | null;
76
+ participants: string[];
77
+ count: number;
78
+ unread: number;
79
+ first_at: string | null;
80
+ last_at: string | null;
81
+ messages: MessageSummary[];
82
+ }
83
+ /**
84
+ * Group messages into threads, newest activity first.
85
+ *
86
+ * A citation only links when the cited file is in the set: a timestamp-shaped
87
+ * string that names nothing is ignored. A subject only links between the same
88
+ * two products, and never when it is empty, so unrelated blank-subject mail
89
+ * does not collapse into one thread.
90
+ */
91
+ export declare function deriveThreads(messages: Message[], now: number): Thread[];
92
+ export type PostState = 'open' | 'expired' | 'closed';
93
+ export interface BoardReply extends MessageSummary {
94
+ /** 'verified' = checked in that session; 'assumed' = recalled. null on a malformed reply. */
95
+ evidence: string | null;
96
+ }
97
+ export interface BoardPost {
98
+ id: string;
99
+ title: string | null;
100
+ from: string;
101
+ tags: string[];
102
+ asked_at: string | null;
103
+ expires_on: string | null;
104
+ state: PostState;
105
+ /** How the asker settled it; null while open. 'nobody' means no one answered. */
106
+ settled_by: string | null;
107
+ /** The closing message, whose body is the one-line resolution. */
108
+ closing: MessageSummary | null;
109
+ post: MessageSummary;
110
+ replies: BoardReply[];
111
+ }
112
+ export interface Board {
113
+ /** One sentence, saying what was counted. */
114
+ headline: string;
115
+ open: BoardPost[];
116
+ closed: BoardPost[];
117
+ }
118
+ /**
119
+ * Board posts with their replies. Open first: expired-and-unanswered at the top
120
+ * (a question nobody answered is the one most likely to be forgotten), then the
121
+ * post closest to expiring. Closed posts newest first.
122
+ *
123
+ * A post is closed when its thread holds a closing message. Archive state is not
124
+ * used: the tool archives a thread on close, but a hand-moved file must not make
125
+ * a question look answered.
126
+ */
127
+ export declare function boardPosts(messages: Message[], now: number): Board;
@@ -0,0 +1,6 @@
1
+ /** The rules and the reader, for building your own view of a mailbox. */
2
+ export * from './board.js';
3
+ export { parseMessage, SETTLED_BY } from './parse.js';
4
+ export { readMailbox, type MailboxMessage } from './read.js';
5
+ export { buildReport } from './view.js';
6
+ export { renderPage, type Report } from './page.js';
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The local page: what is waiting, the board, and threads. One HTML string, no
3
+ * script, no outside request. Every value from a message is escaped: message text
4
+ * is written by other sessions and must never run as markup.
5
+ */
6
+ import type { Board, Thread, WaitingBoard } from './board.js';
7
+ export interface Report {
8
+ mailbox: string;
9
+ generated_at: string;
10
+ total: number;
11
+ waiting: WaitingBoard;
12
+ board: Board;
13
+ threads: Thread[];
14
+ /** Message id → body, for the messages shown. */
15
+ bodies: Record<string, string>;
16
+ }
17
+ export declare function renderPage(r: Report): string;
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The crosstalk message file format, parsed. Pure.
3
+ *
4
+ * A message is a markdown file with a small header block:
5
+ *
6
+ * ---
7
+ * from: web
8
+ * to: api
9
+ * subject: Does checkout accept guests?
10
+ * sent: 2026-11-18T22:16:33Z
11
+ * kind: question
12
+ * thread: 20261118-221633
13
+ * needs_response: yes
14
+ * ---
15
+ *
16
+ * The body.
17
+ */
18
+ /** How a board post can be settled; the tool refuses anything else. */
19
+ export declare const SETTLED_BY: string[];
20
+ /** Parse one message file. `recipient` is the inbox it was found in; `acked` is true when it was found in the archive. */
21
+ export declare function parseMessage(filename: string, raw: string, recipient: string, acked: boolean): {
22
+ filename: string;
23
+ from_session: string;
24
+ to_session: string;
25
+ subject: string | null;
26
+ body: string;
27
+ sent_at: string | null;
28
+ acked: boolean;
29
+ kind: string | null;
30
+ thread_id: string | null;
31
+ reply_to: string | null;
32
+ tags: string[] | null;
33
+ expires_on: string | null;
34
+ evidence: string | null;
35
+ settled_by: string | null;
36
+ };
@@ -0,0 +1,5 @@
1
+ import type { Message } from './board.js';
2
+ export interface MailboxMessage extends Message {
3
+ body: string;
4
+ }
5
+ export declare function readMailbox(root: string): MailboxMessage[];
@@ -0,0 +1,10 @@
1
+ import { type Report } from './page.js';
2
+ export declare const DEFAULT_PORT = 4318;
3
+ export declare function buildReport(root: string, now?: number): Report;
4
+ export declare function parseArgs(args: string[]): {
5
+ root: string;
6
+ html: string | null;
7
+ json: boolean;
8
+ port: number;
9
+ };
10
+ export declare function run(args: string[]): void;
package/package.json CHANGED
@@ -1,18 +1,22 @@
1
1
  {
2
2
  "name": "@point-seven-studio/jq-crosstalk",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "A file mailbox for agent sessions that work side by side: briefs, questions, threads, and a shared board for questions anyone may answer. Plain files on your machine; sends nothing anywhere.",
5
5
  "bin": {
6
6
  "crosstalk": "bin/crosstalk"
7
7
  },
8
8
  "type": "module",
9
9
  "exports": {
10
- ".": "./dist/index.mjs"
10
+ ".": {
11
+ "types": "./dist/types/index.d.ts",
12
+ "default": "./dist/index.mjs"
13
+ }
11
14
  },
12
15
  "files": [
13
16
  "bin/crosstalk",
14
17
  "dist/view.mjs",
15
18
  "dist/index.mjs",
19
+ "dist/types",
16
20
  "README.md",
17
21
  "LICENSE",
18
22
  "NOTICE"
@@ -57,5 +61,6 @@
57
61
  "homepage": "https://github.com/point-seven-studio/jq-tools/tree/main/packages/crosstalk#readme",
58
62
  "bugs": {
59
63
  "url": "https://github.com/point-seven-studio/jq-tools/issues"
60
- }
64
+ },
65
+ "types": "./dist/types/index.d.ts"
61
66
  }