@designtools/comments 0.0.0-stage → 0.1.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.
- package/CHANGELOG.md +13 -0
- package/LICENSE +21 -0
- package/README.md +145 -2
- package/dist/adapter.d.ts +45 -0
- package/dist/adapter.js +177 -0
- package/dist/api.d.ts +20 -0
- package/dist/api.js +35 -0
- package/dist/cli.d.ts +19 -0
- package/dist/cli.js +216 -0
- package/dist/comments.d.ts +24 -0
- package/dist/comments.js +567 -0
- package/dist/css.d.ts +2 -0
- package/dist/css.js +2 -0
- package/dist/identity.d.ts +6 -0
- package/dist/identity.js +66 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +4 -0
- package/dist/server/handler.d.ts +45 -0
- package/dist/server/handler.js +169 -0
- package/dist/server/index.d.ts +11 -0
- package/dist/server/index.js +10 -0
- package/dist/server/memory.d.ts +6 -0
- package/dist/server/memory.js +81 -0
- package/dist/server/migrations.d.ts +17 -0
- package/dist/server/migrations.js +61 -0
- package/dist/server/postgres.d.ts +7 -0
- package/dist/server/postgres.js +100 -0
- package/dist/server/sql.d.ts +14 -0
- package/dist/server/sql.js +36 -0
- package/dist/types.d.ts +112 -0
- package/dist/types.js +5 -0
- package/dist/validate.d.ts +40 -0
- package/dist/validate.js +144 -0
- package/package.json +80 -3
package/dist/cli.js
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* designtools-comments: comments from the terminal, for an agent working through feedback or a
|
|
4
|
+
* person who'd rather not open the page. Reads the same database as the route handler.
|
|
5
|
+
*
|
|
6
|
+
* designtools-comments list [--status open|resolved|all] [--path /about] [--json]
|
|
7
|
+
* designtools-comments resolve <id> [--by <name>]
|
|
8
|
+
* designtools-comments reopen <id> [--by <name>]
|
|
9
|
+
* designtools-comments migrate [--print]
|
|
10
|
+
*
|
|
11
|
+
* The database is --database-url, else COMMENTS_DATABASE_URL, read from the environment or from
|
|
12
|
+
* .env.local or .env in the current directory.
|
|
13
|
+
*/
|
|
14
|
+
import { execFileSync } from "node:child_process";
|
|
15
|
+
import { existsSync, readFileSync, realpathSync } from "node:fs";
|
|
16
|
+
import { join } from "node:path";
|
|
17
|
+
import { pathToFileURL } from "node:url";
|
|
18
|
+
import { parseArgs } from "node:util";
|
|
19
|
+
import { migrate, schemaSql } from "./server/migrations.js";
|
|
20
|
+
import { postgresStore } from "./server/postgres.js";
|
|
21
|
+
import { connect } from "./server/sql.js";
|
|
22
|
+
const HELP = `designtools-comments: list and resolve comments left on previews
|
|
23
|
+
|
|
24
|
+
Usage
|
|
25
|
+
designtools-comments list [--status open|resolved|all] [--path /about] [--json]
|
|
26
|
+
designtools-comments resolve <id> [--by <name>]
|
|
27
|
+
designtools-comments reopen <id> [--by <name>]
|
|
28
|
+
designtools-comments migrate [--print]
|
|
29
|
+
|
|
30
|
+
Options
|
|
31
|
+
--database-url <url> the comments database (default: COMMENTS_DATABASE_URL,
|
|
32
|
+
from the environment, .env.local or .env)
|
|
33
|
+
--status <status> which threads to list (default: open)
|
|
34
|
+
--path <path> only threads on this page, locale included: /de/about
|
|
35
|
+
--json print threads as JSON, for a script or an agent
|
|
36
|
+
--by <name> who is resolving (default: git's user.name)
|
|
37
|
+
--print print the schema's SQL instead of running it
|
|
38
|
+
|
|
39
|
+
An <id> can be shortened to its first 8 or more characters.
|
|
40
|
+
`;
|
|
41
|
+
/** COMMENTS_DATABASE_URL from a dotenv file, the way Next reads one: KEY=value, optionally quoted. */
|
|
42
|
+
export function fromDotenv(text, key) {
|
|
43
|
+
for (const line of text.split(/\r?\n/)) {
|
|
44
|
+
const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
|
|
45
|
+
if (!m || m[1] !== key)
|
|
46
|
+
continue;
|
|
47
|
+
let value = m[2].trim();
|
|
48
|
+
if (/^(["']).*\1$/.test(value))
|
|
49
|
+
value = value.slice(1, -1);
|
|
50
|
+
else
|
|
51
|
+
value = value.replace(/\s+#.*$/, "");
|
|
52
|
+
return value;
|
|
53
|
+
}
|
|
54
|
+
return undefined;
|
|
55
|
+
}
|
|
56
|
+
function databaseUrl(flag, env, cwd) {
|
|
57
|
+
if (flag)
|
|
58
|
+
return flag;
|
|
59
|
+
if (env.COMMENTS_DATABASE_URL)
|
|
60
|
+
return env.COMMENTS_DATABASE_URL;
|
|
61
|
+
for (const file of [".env.local", ".env.development.local", ".env"]) {
|
|
62
|
+
const path = join(cwd, file);
|
|
63
|
+
if (!existsSync(path))
|
|
64
|
+
continue;
|
|
65
|
+
const value = fromDotenv(readFileSync(path, "utf8"), "COMMENTS_DATABASE_URL");
|
|
66
|
+
if (value)
|
|
67
|
+
return value;
|
|
68
|
+
}
|
|
69
|
+
return undefined;
|
|
70
|
+
}
|
|
71
|
+
function whoAmI(env) {
|
|
72
|
+
try {
|
|
73
|
+
const name = execFileSync("git", ["config", "user.name"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
|
|
74
|
+
if (name)
|
|
75
|
+
return name;
|
|
76
|
+
}
|
|
77
|
+
catch { }
|
|
78
|
+
return env.USER || env.USERNAME || "designtools-comments";
|
|
79
|
+
}
|
|
80
|
+
export const anchorLabel = (t) => (t.anchor.field ? `${t.anchor.label} › ${t.anchor.field}` : t.anchor.label);
|
|
81
|
+
const indent = (text, by) => text.replace(/\n/g, `\n${by}`);
|
|
82
|
+
const when = (iso) => iso.slice(0, 16).replace("T", " ");
|
|
83
|
+
/** Threads as a person reads them: one block each, its comments under it. */
|
|
84
|
+
export function formatThreads(threads, status) {
|
|
85
|
+
const noun = status === "all" ? "" : `${status} `;
|
|
86
|
+
if (!threads.length)
|
|
87
|
+
return `No ${noun}threads.`;
|
|
88
|
+
const blocks = threads.map((t) => {
|
|
89
|
+
const head = `${t.id} ${t.path} ${anchorLabel(t)}${status === "all" ? ` [${t.status}]` : ""}`;
|
|
90
|
+
const meta = [t.branch && `branch ${t.branch}`, t.deploymentUrl, when(t.createdAt), t.status === "resolved" && t.resolvedBy ? `resolved by ${t.resolvedBy}` : null].filter(Boolean).join(" · ");
|
|
91
|
+
const lines = t.comments.map((c, i) => `${i ? " " : " "}${c.authorName}: ${indent(c.body, i ? " " : " ")}`);
|
|
92
|
+
return [head, ` ${meta}`, ...lines].join("\n");
|
|
93
|
+
});
|
|
94
|
+
return `${threads.length} ${noun}thread${threads.length === 1 ? "" : "s"}\n\n${blocks.join("\n\n")}`;
|
|
95
|
+
}
|
|
96
|
+
async function findThread(store, id) {
|
|
97
|
+
if (/^[0-9a-f-]{36}$/i.test(id))
|
|
98
|
+
return (await store.get(id)) ?? `No thread ${id}.`;
|
|
99
|
+
if (!/^[0-9a-f-]{8,}$/i.test(id))
|
|
100
|
+
return `"${id}" isn't a thread id. Use the id \`list\` prints, or its first 8 characters.`;
|
|
101
|
+
const matches = (await store.list()).filter((t) => t.id.startsWith(id.toLowerCase()));
|
|
102
|
+
if (matches.length === 1)
|
|
103
|
+
return matches[0];
|
|
104
|
+
return matches.length ? `${id} matches ${matches.length} threads; give more of the id.` : `No thread starting ${id}.`;
|
|
105
|
+
}
|
|
106
|
+
/** Runs one command; resolves to the exit code. */
|
|
107
|
+
export async function run(argv, io) {
|
|
108
|
+
let parsed;
|
|
109
|
+
try {
|
|
110
|
+
parsed = parse(argv);
|
|
111
|
+
}
|
|
112
|
+
catch (e) {
|
|
113
|
+
io.err(`${e.message}\n\n${HELP}`);
|
|
114
|
+
return 2;
|
|
115
|
+
}
|
|
116
|
+
const { values, positionals } = parsed;
|
|
117
|
+
const [command, ...rest] = positionals;
|
|
118
|
+
if (values.help || !command || command === "help") {
|
|
119
|
+
io.out(HELP);
|
|
120
|
+
return command || values.help ? 0 : 2;
|
|
121
|
+
}
|
|
122
|
+
const env = io.env ?? process.env;
|
|
123
|
+
if (command === "migrate" && values.print) {
|
|
124
|
+
io.out(schemaSql());
|
|
125
|
+
return 0;
|
|
126
|
+
}
|
|
127
|
+
const url = databaseUrl(values["database-url"], env, io.cwd ?? process.cwd());
|
|
128
|
+
if (!io.store && !io.sql && !url) {
|
|
129
|
+
io.err("No database: set COMMENTS_DATABASE_URL (in the environment or .env.local), or pass --database-url.");
|
|
130
|
+
return 1;
|
|
131
|
+
}
|
|
132
|
+
const sql = io.sql ?? (io.store ? undefined : connect(url));
|
|
133
|
+
const store = io.store ?? postgresStore(sql);
|
|
134
|
+
try {
|
|
135
|
+
switch (command) {
|
|
136
|
+
case "list": {
|
|
137
|
+
const status = (values.status ?? "open");
|
|
138
|
+
if (!["open", "resolved", "all"].includes(status)) {
|
|
139
|
+
io.err('--status must be "open", "resolved" or "all".');
|
|
140
|
+
return 2;
|
|
141
|
+
}
|
|
142
|
+
const threads = await store.list({ path: values.path, status: status === "all" ? undefined : status });
|
|
143
|
+
io.out(values.json ? JSON.stringify(threads, null, 2) : formatThreads(threads, status));
|
|
144
|
+
return 0;
|
|
145
|
+
}
|
|
146
|
+
case "resolve":
|
|
147
|
+
case "reopen": {
|
|
148
|
+
const [id] = rest;
|
|
149
|
+
if (!id) {
|
|
150
|
+
io.err(`Which thread? designtools-comments ${command} <id>`);
|
|
151
|
+
return 2;
|
|
152
|
+
}
|
|
153
|
+
const found = await findThread(store, id);
|
|
154
|
+
if (typeof found === "string") {
|
|
155
|
+
io.err(found);
|
|
156
|
+
return 1;
|
|
157
|
+
}
|
|
158
|
+
const status = command === "resolve" ? "resolved" : "open";
|
|
159
|
+
if (found.status === status) {
|
|
160
|
+
io.out(`Already ${status}: ${found.id} (${anchorLabel(found)} on ${found.path}).`);
|
|
161
|
+
return 0;
|
|
162
|
+
}
|
|
163
|
+
await store.setStatus(found.id, status, values.by ?? whoAmI(env));
|
|
164
|
+
io.out(`${command === "resolve" ? "Resolved" : "Reopened"} ${found.id} (${anchorLabel(found)} on ${found.path}).`);
|
|
165
|
+
return 0;
|
|
166
|
+
}
|
|
167
|
+
case "migrate": {
|
|
168
|
+
if (!sql) {
|
|
169
|
+
io.err("migrate needs a database.");
|
|
170
|
+
return 1;
|
|
171
|
+
}
|
|
172
|
+
const applied = await migrate(sql);
|
|
173
|
+
io.out(applied.length ? `Applied migration${applied.length === 1 ? "" : "s"} ${applied.join(", ")}.` : "Already up to date.");
|
|
174
|
+
return 0;
|
|
175
|
+
}
|
|
176
|
+
default:
|
|
177
|
+
io.err(`Unknown command "${command}".\n\n${HELP}`);
|
|
178
|
+
return 2;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
finally {
|
|
182
|
+
// a client the CLI opened itself is closed; one it was handed belongs to the caller
|
|
183
|
+
if (!io.sql && !io.store)
|
|
184
|
+
await store.close?.();
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
function parse(argv) {
|
|
188
|
+
return parseArgs({
|
|
189
|
+
args: argv,
|
|
190
|
+
allowPositionals: true,
|
|
191
|
+
options: {
|
|
192
|
+
"database-url": { type: "string" },
|
|
193
|
+
status: { type: "string" },
|
|
194
|
+
path: { type: "string" },
|
|
195
|
+
json: { type: "boolean" },
|
|
196
|
+
by: { type: "string" },
|
|
197
|
+
print: { type: "boolean" },
|
|
198
|
+
help: { type: "boolean", short: "h" },
|
|
199
|
+
},
|
|
200
|
+
});
|
|
201
|
+
}
|
|
202
|
+
/** Whether this file is what node was asked to run, through the bin's symlink or not, rather than imported by a test. */
|
|
203
|
+
function isMain() {
|
|
204
|
+
try {
|
|
205
|
+
return !!process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
|
|
206
|
+
}
|
|
207
|
+
catch {
|
|
208
|
+
return false;
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
if (isMain()) {
|
|
212
|
+
run(process.argv.slice(2), { out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) }).then((code) => process.exit(code), (e) => {
|
|
213
|
+
process.stderr.write(`${e.message}\n`);
|
|
214
|
+
process.exit(1);
|
|
215
|
+
});
|
|
216
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Comments on a prototype, pinned to the part of the page they're about. `<Comments />` draws a
|
|
3
|
+
* launcher in the corner; Comment starts choosing (mouse, or arrow keys and Enter), and what's
|
|
4
|
+
* chosen gets a thread. Open threads show as pins beside their anchors; the panel lists this page's
|
|
5
|
+
* threads, open or resolved, and the ones whose anchor has gone.
|
|
6
|
+
*
|
|
7
|
+
* Everything is drawn in its own shadow root, apart from the page. It asks its route handler first
|
|
8
|
+
* and draws nothing when that answers 404, as it does in production.
|
|
9
|
+
*/
|
|
10
|
+
import { type Theme } from "@designtools/widgets";
|
|
11
|
+
import { type AnchorAdapter } from "./adapter.js";
|
|
12
|
+
export interface CommentsProps {
|
|
13
|
+
/** Where the route handler is mounted. */
|
|
14
|
+
endpoint?: string;
|
|
15
|
+
/** What can be commented on. By default, `data-comment-anchor` attributes, else any element. */
|
|
16
|
+
adapter?: AnchorAdapter;
|
|
17
|
+
/** Force the tool off. When on, it still draws nothing unless the route handler answers. */
|
|
18
|
+
enabled?: boolean;
|
|
19
|
+
theme?: Theme;
|
|
20
|
+
/** The page's locale, stored with each thread. By default `<html lang>`. */
|
|
21
|
+
locale?: () => string | null;
|
|
22
|
+
}
|
|
23
|
+
export declare function ago(iso: string, now?: number): string;
|
|
24
|
+
export declare function Comments({ endpoint, adapter: adapterProp, enabled, theme, locale }: CommentsProps): import("react").JSX.Element | null;
|