@point-seven-studio/jq-deck 0.0.0-stage → 0.3.0

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,54 @@
1
+ import { type DeckOptions } from './collect.js';
2
+ import { type Overview } from './deck.js';
3
+ export declare const DEFAULT_PORT = 4316;
4
+ export interface Args {
5
+ json: boolean;
6
+ watch: boolean;
7
+ exec: string | null;
8
+ intervalS: number;
9
+ /** Repositories --watch may report. null: not said on the command line. */
10
+ repos: string[] | null;
11
+ allRepos: boolean;
12
+ /** Folders whose question text --watch may send. null: not said on the command line. */
13
+ sendQuestions: string[] | null;
14
+ port: number;
15
+ mailbox: string | null;
16
+ config: string;
17
+ questionTrees: string[] | null;
18
+ probe: boolean;
19
+ sample: boolean;
20
+ maxAgeDays: number;
21
+ }
22
+ export declare function parseArgs(argv: string[], env?: Record<string, string | undefined>): Args;
23
+ export interface Context {
24
+ port: number;
25
+ version: string;
26
+ deck: DeckOptions;
27
+ probe: boolean;
28
+ sample: boolean;
29
+ /** What --watch may report: a list, or null for every repository. */
30
+ report: string[] | null;
31
+ /** Folders whose question text --watch may send. Empty unless asked for. */
32
+ sendQuestions: string[];
33
+ }
34
+ /**
35
+ * Which repositories a machine reports. Naming them is required: a machine
36
+ * often holds work for more than one team, and a repository's name alone can
37
+ * be something its owner did not agree to share.
38
+ */
39
+ export declare function reportList(a: Pick<Args, 'repos' | 'allRepos'>, fromConfig: string[] | undefined): string[] | null;
40
+ /** Flags, then the config file, then the environment. */
41
+ export declare function buildContext(a: Args, env: Record<string, string | undefined>, cwd: string, version: string): Context;
42
+ export interface Reply {
43
+ status: number;
44
+ type: 'text/html; charset=utf-8' | 'text/plain; charset=utf-8';
45
+ body: string;
46
+ }
47
+ /**
48
+ * A page on another site can make a browser call 127.0.0.1 under a name that
49
+ * site controls. Answering only to this machine's own names stops it reading
50
+ * the reply.
51
+ */
52
+ export declare function hostAllowed(host: string | undefined, port: number): boolean;
53
+ export declare function handle(url: string, host: string | undefined, ctx: Context, overview?: (o: DeckOptions) => Promise<Overview>): Promise<Reply>;
54
+ export declare function run(argv: string[], version: string): Promise<void>;
@@ -0,0 +1,18 @@
1
+ import { type CollectOptions, type Snapshot } from '@point-seven-studio/jq-agents';
2
+ import { type Overview, type SetupResult } from './deck.js';
3
+ export interface DeckOptions extends CollectOptions {
4
+ mailbox: string | null;
5
+ names?: Record<string, string>;
6
+ /** Shown as a repository even with no session in it, when it looks like one. */
7
+ cwd?: string;
8
+ }
9
+ /** A folder worth a row with no session in it: it has a repository or a Claude Code setup. */
10
+ export declare function looksLikeProject(dir: string): boolean;
11
+ export declare function checkSetup(tree: string): SetupResult;
12
+ /**
13
+ * The origin remote of a folder, read from its git config file. No git command
14
+ * is run. A worktree's .git is a file pointing at the real one; follow it.
15
+ */
16
+ export declare function remoteOf(tree: string): string | null;
17
+ export declare function treesOf(snap: Snapshot, cwd?: string): string[];
18
+ export declare function collectOverview(opts: DeckOptions): Promise<Overview>;
@@ -0,0 +1,164 @@
1
+ import { type Snapshot } from '@point-seven-studio/jq-agents';
2
+ import type { WaitingBoard } from '@point-seven-studio/jq-crosstalk';
3
+ import type { Summary } from '@point-seven-studio/jq-groundcrew';
4
+ export interface DeckConfig {
5
+ /** The crosstalk mailbox folder. */
6
+ mailbox?: string;
7
+ /** Inbox name → repository folder, for when the two are not named alike. */
8
+ names?: Record<string, string>;
9
+ /** Folders whose waiting sessions may show their question text. */
10
+ questions?: string[];
11
+ /** The repositories --watch may report to a team board: names, remotes or folders. */
12
+ report?: string[];
13
+ /** Folders whose waiting sessions may send their question text to a team board. */
14
+ sendQuestions?: string[];
15
+ }
16
+ export declare const expandHome: (p: string) => string;
17
+ export declare function defaultConfigFile(): string;
18
+ /** A missing file is no config. A file that cannot be parsed is an error, named. */
19
+ export declare function loadConfig(file: string): DeckConfig;
20
+ /**
21
+ * Which mailbox: the flag, then the config file, then $CROSSTALK_DIR, then the
22
+ * nearest folder above `cwd` holding a .crosstalk file. The same order the
23
+ * `crosstalk` command uses for the last two. null when there is none.
24
+ */
25
+ export declare function findMailbox(opts: {
26
+ flag?: string | null;
27
+ config?: string;
28
+ env?: string;
29
+ cwd: string;
30
+ }): string | null;
31
+ /** A short, stable id for a folder, so a URL never carries a path. */
32
+ export declare const repoId: (tree: string) => string;
33
+ /**
34
+ * The inbox for a folder when the config file names none: the inbox with exactly
35
+ * the folder's name, else the only inbox the folder's name starts with before a
36
+ * separator ("shop-v2" → "shop"). Two candidates is no match: a wrong inbox
37
+ * would show another session's unread count.
38
+ */
39
+ export declare function matchInbox(folder: string, inboxes: string[]): string | null;
40
+ export type SetupResult = {
41
+ summary: Summary;
42
+ } | {
43
+ error: string;
44
+ };
45
+ export interface RepoRow {
46
+ id: string;
47
+ name: string;
48
+ tree: string;
49
+ sessions: number;
50
+ live: number;
51
+ /** Sessions that ended their turn and are alive: they need a person now. */
52
+ needs_you: number;
53
+ /** Sessions that asked something and were left. */
54
+ abandoned: number;
55
+ last_activity_at: string | null;
56
+ /** When the longest-waiting session that needs a person last did anything. */
57
+ waiting_since: string | null;
58
+ /**
59
+ * What each session that needs a person asked, longest-waiting first. Only
60
+ * for folders where question text is allowed; empty everywhere else.
61
+ */
62
+ questions: {
63
+ asked_at: string | null;
64
+ text: string;
65
+ }[];
66
+ /** The origin remote as host/owner/name, when the folder has one. Names the same repository on two machines. */
67
+ remote: string | null;
68
+ /** null when the setup check could not run; `setup_note` says why. */
69
+ setup: {
70
+ score: number;
71
+ fail: number;
72
+ warn: number;
73
+ } | null;
74
+ setup_note: string | null;
75
+ /** The inbox matched to this repository, or null when none matches. */
76
+ inbox: string | null;
77
+ /** null when there is no matched inbox: unknown, never zero. */
78
+ unread: number | null;
79
+ oldest_unread_days: number | null;
80
+ }
81
+ export interface Overview {
82
+ machine: string;
83
+ generated_at: string;
84
+ /** One sentence. Says what was counted, so zero never reads as "failed to load". */
85
+ headline: string;
86
+ repos: RepoRow[];
87
+ mailbox: string | null;
88
+ /** null when no mailbox was found, or it could not be read (`mail_note`). */
89
+ mail: {
90
+ total_unread: number;
91
+ headline: string;
92
+ unmatched: {
93
+ inbox: string;
94
+ unread: number;
95
+ }[];
96
+ } | null;
97
+ mail_note: string | null;
98
+ }
99
+ export declare function buildHeadline(repos: RepoRow[], mail: Overview['mail'], mailNote: string | null): string;
100
+ export declare function buildOverview(input: {
101
+ snapshot: Snapshot;
102
+ /** Every repository to show: the trees with a session, plus any others. */
103
+ trees: string[];
104
+ setups: Map<string, SetupResult>;
105
+ /** null when there is no mailbox, or it could not be read. */
106
+ waiting: WaitingBoard | null;
107
+ /** Every inbox in the mailbox, so "no unread" can be told from "no inbox". */
108
+ inboxes?: string[];
109
+ mailbox: string | null;
110
+ mailNote?: string | null;
111
+ names?: Record<string, string>;
112
+ /** Folder → origin remote, as host/owner/name. */
113
+ remotes?: Map<string, string>;
114
+ }): Overview;
115
+ /**
116
+ * "git@github.com:acme/shop.git" and "https://github.com/acme/shop" are both
117
+ * "github.com/acme/shop". Any user name or token in the address is dropped.
118
+ * null when the address is not one of the shapes git hosts use.
119
+ */
120
+ export declare function normalizeRemote(url: string): string | null;
121
+ /** The url of [remote "origin"] in a git config file's text. */
122
+ export declare function originIn(config: string): string | null;
123
+ /**
124
+ * What one machine tells a team board: counts and scores per repository. It
125
+ * carries no folder path, no question text, no message and no file name.
126
+ */
127
+ export interface TeamReport {
128
+ v: 1;
129
+ generated_at: string;
130
+ repos: {
131
+ name: string;
132
+ remote: string | null;
133
+ sessions: number;
134
+ live: number;
135
+ needs_you: number;
136
+ abandoned: number;
137
+ waiting_since: string | null;
138
+ last_activity_at: string | null;
139
+ setup: {
140
+ score: number;
141
+ fail: number;
142
+ warn: number;
143
+ } | null;
144
+ unread: number | null;
145
+ /** Present only for a repository whose folder opted in to sending question text. */
146
+ questions?: {
147
+ asked_at: string | null;
148
+ text: string;
149
+ }[];
150
+ }[];
151
+ }
152
+ /** Is `tree` one of these folders, or inside one? */
153
+ export declare function under(tree: string, folders: string[]): boolean;
154
+ /** Is this repository on the list? An entry is a folder name, a remote (host/owner/name) or a folder path. */
155
+ export declare function reportable(r: Pick<RepoRow, 'name' | 'remote' | 'tree'>, only: string[]): boolean;
156
+ /**
157
+ * `only` is the list of repositories this machine agreed to report. With a
158
+ * list, nothing else is in the report, not even as a count. null reports all.
159
+ *
160
+ * `sendQuestions` is the list of folders that agreed to send what a waiting
161
+ * session asked. It defaults to none, whatever the overview holds: showing a
162
+ * question on your own screen is not agreeing to send it.
163
+ */
164
+ export declare function teamReport(o: Overview, only?: string[] | null, sendQuestions?: string[]): TeamReport;
@@ -0,0 +1,5 @@
1
+ /** The join and the shell page, for building your own view over the three tools. */
2
+ export * from './deck.js';
3
+ export { checkSetup, collectOverview, looksLikeProject, remoteOf, treesOf, type DeckOptions } from './collect.js';
4
+ export { pickRepo, renderShell, TABS, type Tab } from './page.js';
5
+ export { buildContext, DEFAULT_PORT, handle, hostAllowed, parseArgs, reportList, type Args, type Context, type Reply } from './cli.js';
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,11 @@
1
+ /**
2
+ * JQ Deck: the shell page. A header, four tabs, and under them either the
3
+ * overview table or one tool's own page in a frame. One HTML string, no script,
4
+ * no outside request. Every value is escaped: names and paths come from disk.
5
+ */
6
+ import type { Overview, RepoRow } from './deck.js';
7
+ export declare const TABS: readonly ["overview", "sessions", "setup", "mail"];
8
+ export type Tab = (typeof TABS)[number];
9
+ /** The repository the Setup tab opens on: the asked one, else the first with something to fix. */
10
+ export declare function pickRepo(repos: RepoRow[], asked: string | null): RepoRow | null;
11
+ export declare function renderShell(o: Overview, tab: Tab, repo: string | null, version: string): string;
package/package.json CHANGED
@@ -1,6 +1,64 @@
1
1
  {
2
2
  "name": "@point-seven-studio/jq-deck",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.0",
4
+ "description": "One command, one local page: every Claude Code session on your machine, the setup check for each repository, and the mailbox between sessions. Read-only; sends nothing anywhere. Unofficial; not affiliated with or endorsed by Anthropic.",
5
+ "bin": {
6
+ "jq-deck": "dist/jq-deck.mjs"
7
+ },
8
+ "type": "module",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/types/index.d.ts",
12
+ "default": "./dist/index.mjs"
13
+ }
14
+ },
15
+ "types": "./dist/types/index.d.ts",
16
+ "files": [
17
+ "dist/jq-deck.mjs",
18
+ "dist/index.mjs",
19
+ "dist/types",
20
+ "README.md",
21
+ "LICENSE",
22
+ "NOTICE"
23
+ ],
24
+ "engines": {
25
+ "node": ">=18"
26
+ },
27
+ "keywords": [
28
+ "claude-code",
29
+ "coding-agents",
30
+ "multi-agent",
31
+ "developer-tools",
32
+ "ai-coding"
33
+ ],
34
+ "author": "Point Seven Studio",
35
+ "license": "Apache-2.0",
36
+ "repository": {
37
+ "type": "git",
38
+ "url": "git+https://github.com/point-seven-studio/jq-tools.git",
39
+ "directory": "packages/deck"
40
+ },
41
+ "homepage": "https://github.com/point-seven-studio/jq-tools/tree/main/packages/deck#readme",
42
+ "bugs": {
43
+ "url": "https://github.com/point-seven-studio/jq-tools/issues"
44
+ },
45
+ "scripts": {
46
+ "typecheck": "tsc --noEmit",
47
+ "test": "vitest run",
48
+ "build": "./build.sh",
49
+ "check": "./build.sh --deps && npm run typecheck && npm test && ./build.sh --check",
50
+ "prepublishOnly": "npm run check"
51
+ },
52
+ "devDependencies": {
53
+ "@point-seven-studio/jq-agents": "^0.1.1",
54
+ "@point-seven-studio/jq-crosstalk": "^0.1.1",
55
+ "@point-seven-studio/jq-groundcrew": "^0.1.2",
56
+ "@types/node": "^20.14.0",
57
+ "esbuild": "^0.21.5",
58
+ "typescript": "^5.4.5",
59
+ "vitest": "^1.6.0"
60
+ },
61
+ "publishConfig": {
62
+ "access": "public"
63
+ }
64
+ }