@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.
Files changed (3) hide show
  1. package/SKILL.md +2 -0
  2. package/handout.mjs +28 -9
  3. 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({ label: external_exports.string(), count: external_exports.number().int().nonnegative() });
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.4.0".length > 0) {
22058
- cachedVersion = "1.4.0";
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) => ` ${item.label.padEnd(width)} ${plural2(item.count, "document")}`);
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.4.0".length > 0;
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 only = warnings.length === 1 ? warnings[0] : void 0;
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.4.0",
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",