@usehandout/cli 1.4.0 → 1.5.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/SKILL.md +2 -0
- package/handout.mjs +28 -9
- package/package.json +1 -1
package/SKILL.md
CHANGED
|
@@ -121,6 +121,7 @@ Each workspace keeps a short, editable list of suggested labels. Before you labe
|
|
|
121
121
|
2. Pick from `suggested`, one or two per document. Reuse an existing spelling instead of a variant (`Plan` vs `plan`).
|
|
122
122
|
3. If nothing on the list fits, **ask the user before inventing a label**. A free-text label is still accepted, but a guessed one becomes a permanent near-duplicate. When `suggested` is empty and `seedable` is true, the workspace already uses labels and has no list yet: do not invent one; tell the user they can adopt the suggested set on the workspace's settings page.
|
|
123
123
|
4. When two or more documents share a project, client or period, **suggest a collection** (`handout collections create` and `collections add`) instead of a label, and ask before creating it. `handout list --collection <slug>` lists what is in one, and `handout get <slug>` shows the collections a document is in. Never label a document with its collection's name.
|
|
124
|
+
5. A `suggested` or `other` entry may carry `matchesCollection: { slug, name }`: every document with that label is exactly the members of that collection, so the label stores the same fact twice. **Suggest the collection to the user** ("Every document labelled `q3` is already in the Q3 pack collection; use the collection instead?") and do not apply that label to new documents. It is a suggestion only: never remove the label, add or remove collection members, or delete anything because of it unless the user says to.
|
|
124
125
|
|
|
125
126
|
The user's account `defaultLabels` setting is separate: it stamps labels on every publish, and you never change it unless asked.
|
|
126
127
|
|
|
@@ -133,6 +134,7 @@ The user's account `defaultLabels` setting is separate: it stamps labels on ever
|
|
|
133
134
|
5. Give it a short, real title: the document's own `<title>` or first heading, or `--title "<short title>"` when it has none (always for a PDF). The link is made from the title plus 8 random characters (`q3-report-k7f2qx9a`), so it reads well and still can't be guessed. Anyone who sees the link sees those title words, whatever the audience, so for a sensitive document ask the user for a neutral title. Leave out `--slug` unless the user asks for a specific link; then pass a short kebab-case one (`--slug q3-report`) and tell them a link like that can be guessed by anyone who knows the workspace, which matters for "anyone with the link" and password documents.
|
|
134
135
|
6. Choose labels as described in Labels and collections (`handout labels --json`, pick from `suggested`, ask before inventing one). Run `handout publish <file> [--exposure ...] [--title ...] [--label ...] --json` and read `items[0].url`, `slug`, `version` and `warnings`.
|
|
135
136
|
7. Report the URL to the user verbatim. If `warnings` is not empty, summarise each in one line and offer to fix the file and run `handout update <slug> <file>`.
|
|
137
|
+
A `pdf_no_text` warning means the PDF is published but "We couldn't find much searchable text in this PDF. If it's a scan, running OCR and republishing will make it searchable." Pass that on in one line, then offer to make it searchable: run text recognition (OCR) on the file locally and publish the result as a new version of the same document. Ask the user first; never OCR or republish unasked. When they agree and `ocrmypdf` is installed (`ocrmypdf --version`), run `ocrmypdf --skip-text <file> <file-ocr>.pdf`, then `handout update <slug> <file-ocr>.pdf --diff-summary "Made the text searchable."`. If no OCR tool is available, tell them and leave the document as it is. Handout itself never runs OCR.
|
|
136
138
|
8. If the slug came back as 12 random characters (`aB3xY9zQ1pR7`), the document had no usable title. Rename it at once, before the link is shared, since a rename breaks the old link: `handout rename <slug> <kebab-case-title>-<8 random lowercase letters and digits>`. Give later versions a title.
|
|
137
139
|
9. Remember the slug for the rest of the conversation. Later edits are `handout update <slug> <file>` (same link, new version), never a second `publish`, which mints a second link. `handout upsert <file> --slug <slug>` creates or updates in one call when you already know the slug.
|
|
138
140
|
Every update carries a change note by default: `--diff-summary "<one line on what changed>"`, written for the readers ("Added the Q4 numbers and fixed the totals table."), not as a commit message. Readers who come back see it as "What's new in v{n}", followers get it in their update email, and it is listed in the version history. Keep it to one sentence (it shows up to 280 characters; 500 is the hard limit), never paste the document or anything secret into it, and leave it out only when the user asks.
|
package/handout.mjs
CHANGED
|
@@ -20005,6 +20005,7 @@ var PreferencesRecord = external_exports.object({
|
|
|
20005
20005
|
cliConnectedAt: external_exports.string().optional(),
|
|
20006
20006
|
ageConfirmedAt: external_exports.string().optional(),
|
|
20007
20007
|
plusConfirmationSentFor: external_exports.string().optional(),
|
|
20008
|
+
signupCountedAt: external_exports.string().optional(),
|
|
20008
20009
|
deletionRequestedAt: external_exports.string().optional(),
|
|
20009
20010
|
suspendedAt: external_exports.string().nullable().default(null),
|
|
20010
20011
|
suspendedReason: external_exports.string().nullable().default(null),
|
|
@@ -20180,6 +20181,12 @@ function limitsFor(plan) {
|
|
|
20180
20181
|
var HANDLE_MIN_LENGTH = 3;
|
|
20181
20182
|
var HANDLE_MAX_LENGTH = 32;
|
|
20182
20183
|
var HANDLE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
20184
|
+
var HANDLE_SHAPE = `[a-z0-9-]{${HANDLE_MIN_LENGTH},${HANDLE_MAX_LENGTH}}`;
|
|
20185
|
+
var PUBLIC_PATH_SHAPES = Object.freeze({
|
|
20186
|
+
collection: `^/${HANDLE_SHAPE}/c/[^/]+$`,
|
|
20187
|
+
document: `^/${HANDLE_SHAPE}/[^/]+$`,
|
|
20188
|
+
workspace: `^/${HANDLE_SHAPE}$`
|
|
20189
|
+
});
|
|
20183
20190
|
var RESERVED_HANDLES = new Set([
|
|
20184
20191
|
"app",
|
|
20185
20192
|
"api",
|
|
@@ -20436,7 +20443,11 @@ var PatchWorkspaceRequest = external_exports.object({
|
|
|
20436
20443
|
suggestedLabels: SuggestedLabels.optional(),
|
|
20437
20444
|
expectedUpdatedAt: IsoInstant.optional()
|
|
20438
20445
|
});
|
|
20439
|
-
var LabelUsage = external_exports.object({
|
|
20446
|
+
var LabelUsage = external_exports.object({
|
|
20447
|
+
label: external_exports.string(),
|
|
20448
|
+
count: external_exports.number().int().nonnegative(),
|
|
20449
|
+
matchesCollection: external_exports.object({ slug: external_exports.string(), name: external_exports.string() }).optional()
|
|
20450
|
+
});
|
|
20440
20451
|
var WorkspaceLabelsResponse = external_exports.object({
|
|
20441
20452
|
suggested: external_exports.array(LabelUsage),
|
|
20442
20453
|
other: external_exports.array(LabelUsage),
|
|
@@ -20541,7 +20552,8 @@ var HtmlLintCode = external_exports.enum([
|
|
|
20541
20552
|
"fixed-position",
|
|
20542
20553
|
"data-uri-image",
|
|
20543
20554
|
"blocked-external-images",
|
|
20544
|
-
"interactive-unsanitized"
|
|
20555
|
+
"interactive-unsanitized",
|
|
20556
|
+
"pdf_no_text"
|
|
20545
20557
|
]);
|
|
20546
20558
|
var HtmlLintWarning = external_exports.object({
|
|
20547
20559
|
code: HtmlLintCode,
|
|
@@ -21214,7 +21226,8 @@ var ReaderSearchItem = external_exports.object({
|
|
|
21214
21226
|
}).extend(ReaderItemMeta.shape);
|
|
21215
21227
|
var ReaderSearchResponse = external_exports.object({
|
|
21216
21228
|
query: external_exports.string(),
|
|
21217
|
-
items: external_exports.array(ReaderSearchItem)
|
|
21229
|
+
items: external_exports.array(ReaderSearchItem),
|
|
21230
|
+
nextCursor: external_exports.string().optional()
|
|
21218
21231
|
});
|
|
21219
21232
|
var BrowseResponse = external_exports.object({
|
|
21220
21233
|
documents: external_exports.array(CatalogDocumentItem),
|
|
@@ -22054,8 +22067,8 @@ var cachedVersion;
|
|
|
22054
22067
|
function bundledVersion() {
|
|
22055
22068
|
if (cachedVersion !== void 0)
|
|
22056
22069
|
return cachedVersion;
|
|
22057
|
-
if ("1.
|
|
22058
|
-
cachedVersion = "1.
|
|
22070
|
+
if ("1.5.0".length > 0) {
|
|
22071
|
+
cachedVersion = "1.5.0";
|
|
22059
22072
|
return cachedVersion;
|
|
22060
22073
|
}
|
|
22061
22074
|
try {
|
|
@@ -25264,6 +25277,9 @@ async function readTargets(options, fs = nodePublishFs) {
|
|
|
25264
25277
|
return targets;
|
|
25265
25278
|
}
|
|
25266
25279
|
function lintHeader(warnings) {
|
|
25280
|
+
if (warnings.length > 0 && warnings.every((w) => w.code === "pdf_no_text")) {
|
|
25281
|
+
return "Published, with a note on search:";
|
|
25282
|
+
}
|
|
25267
25283
|
return warnings.length === 1 && warnings[0]?.code === "interactive-unsanitized" ? "Published (interactive):" : "Published, but this HTML may render degraded in the reader:";
|
|
25268
25284
|
}
|
|
25269
25285
|
function printLintWarnings(ctx, warnings, prefix) {
|
|
@@ -28154,7 +28170,11 @@ var USAGE_TEXT = buildUsage({
|
|
|
28154
28170
|
});
|
|
28155
28171
|
function rows(items) {
|
|
28156
28172
|
const width = Math.max(0, ...items.map((item) => item.label.length));
|
|
28157
|
-
return items.map((item) =>
|
|
28173
|
+
return items.map((item) => {
|
|
28174
|
+
const row2 = ` ${item.label.padEnd(width)} ${plural2(item.count, "document")}`;
|
|
28175
|
+
const match = item.matchesCollection;
|
|
28176
|
+
return match === void 0 ? row2 : `${row2} (all in collection "${match.name}" (${match.slug}); suggest the collection instead)`;
|
|
28177
|
+
});
|
|
28158
28178
|
}
|
|
28159
28179
|
function formatLabels(data) {
|
|
28160
28180
|
const lines = [];
|
|
@@ -28269,7 +28289,7 @@ function packagedSkillPath(env, moduleUrl = import.meta.url) {
|
|
|
28269
28289
|
if (override !== void 0 && override !== "")
|
|
28270
28290
|
return resolve(override);
|
|
28271
28291
|
const here = dirname2(fileURLToPath(moduleUrl));
|
|
28272
|
-
const bundled = "1.
|
|
28292
|
+
const bundled = "1.5.0".length > 0;
|
|
28273
28293
|
return bundled ? join4(here, "SKILL.md") : join4(here, "..", "..", "SKILL.md");
|
|
28274
28294
|
}
|
|
28275
28295
|
var INSTALL_USAGE = buildUsage({
|
|
@@ -28961,8 +28981,7 @@ async function runCommand(argv, deps = defaultDeps()) {
|
|
|
28961
28981
|
function printLintWarnings2(ctx, warnings, prefix) {
|
|
28962
28982
|
if (ctx.json || warnings === void 0 || warnings.length === 0)
|
|
28963
28983
|
return;
|
|
28964
|
-
const
|
|
28965
|
-
const header = only?.code === "interactive-unsanitized" ? "Published (interactive):" : "Published, but this HTML may render degraded in the reader:";
|
|
28984
|
+
const header = lintHeader(warnings);
|
|
28966
28985
|
const lines = warnings.map((w) => ` - ${w.message}`);
|
|
28967
28986
|
if (prefix !== void 0)
|
|
28968
28987
|
ctx.warn(`${prefix}:`, header, ...lines);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@usehandout/cli",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "The handout command: publish HTML, Markdown and PDF files as Handout links, and the agent skill that lets Claude Code, Codex and other agents do it.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"handout",
|