html-collab 0.1.0 → 0.1.1

package/README.md

@@ -46,7 +46,8 @@ revision can be done by a human or an agent.
 - Suggested edits can be replacements, inserts, or deletions. Toggle between
   the tracked-change markup and a clean preview.
 - Autosave back to the same local file when a Chromium browser asks for
-  permission. Until you choose a local file, changes live only in the tab.
+  permission. Safari and Firefox keep changes in the tab until you export or
+  save another way.
 
 Send your edited file to anyone else with `html-collab merge` to combine
 copies, and `html-collab extract` to pull out a brief.
@@ -61,6 +62,10 @@ Requires Node.js 18+ and npm. No clone or install step is needed:
 npx html-collab wrap report.html --out report.review.html
 ```
 
+The command writes a self-contained review file and prints a short summary.
+Small source files grow by roughly 90 KB because the review UI is embedded
+inside the HTML.
+
 Open `report.review.html` in your browser, mark it up, then export a brief:
 
 ```sh
@@ -78,7 +83,7 @@ you want another round.
 
 ```sh
 npx html-collab wrap report.html --out report.review.html
-# Open report.review.html in any browser. Mark it up. Click Brief.
+# Open report.review.html in your browser. Mark it up. Click Brief.
 npx html-collab extract report.review.html --format markdown --out brief.md
 ```
 
@@ -108,6 +113,8 @@ review file when Autosave asks where to save.
 ## CLI reference
 
 ```
+html-collab --help
+html-collab --version
 html-collab wrap    <input.html>        --out <output.review.html>
 html-collab unwrap  <input.review.html> [--apply-edits] --out <output.html>
 html-collab merge   <a.review.html> <b.review.html> [more...] --out <merged.review.html>
@@ -116,12 +123,15 @@ html-collab skill   --out html-collab.SKILL.md
 ```
 
 Use `npx html-collab ...` if you have not installed the CLI globally.
-The `skill` command writes an optional agent workflow file for tools that
-support local skills.
+The browser Brief button exports markdown. For JSON, plain text, or an
+agent-oriented plan, use `html-collab extract --format <json|text|agent>`.
+The `skill` command writes an optional agent workflow file you can drop into
+a local skills directory or paste into an agent prompt.
 
-`unwrap --apply-edits` writes the final document with accepted edits applied.
-Ambiguous edits fail instead of guessing, so the output is never silently
-wrong.
+`unwrap --apply-edits` only applies suggested edits that have been accepted
+in the browser. Open, rejected, and deleted edits are skipped and reported in
+the command summary. Ambiguous edits fail instead of guessing, so the output
+is never silently wrong.
 
 ## How it works
 
@@ -134,6 +144,8 @@ panel shows.
 
 For mission, principles, and workflows, see the
 [project notes](https://github.com/glendigity/html-collab/blob/main/docs/README.md).
+For a fresh external sanity check, use the
+[independent user test prompt](https://github.com/glendigity/html-collab/blob/main/USER_TEST_PROMPT.md).
 
 ## Status
 

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { realpathSync } from "node:fs";
-import { basename as basename2 } from "node:path";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename as basename2, dirname as dirname3, join as join2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/commands/extract.ts
@@ -2987,6 +2987,7 @@ function renderReviewShell(source, state) {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <meta name="generator" content="html-collab">
+  <link rel="icon" href="data:,">
   <link rel="author" href="${PROJECT_URL}">
   <title>${escapeHtml(state.title ?? "Reviewable HTML")}</title>
   <style>
@@ -3845,6 +3846,12 @@ async function mergeFiles(inputPaths, outputPath) {
   const result = mergeReviewStates(states);
   const mergedHtml = createReviewHtmlFromParts(source, result.state);
   await writeFile2(outputPath, mergedHtml, "utf8");
+  return {
+    addedOps: result.addedOps,
+    addedActors: result.addedActors,
+    totalOps: result.state.ops.length,
+    reviewBytes: Buffer.byteLength(mergedHtml, "utf8")
+  };
 }
 
 // src/commands/skill.ts
@@ -3890,7 +3897,8 @@ import { readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises
 
 // src/format/apply-edits.ts
 function applyAcceptedEdits(sourceHtml, state) {
-  const accepted = reduceReviewState(state).edits.filter((edit) => edit.status === "accepted");
+  const reduced = reduceReviewState(state);
+  const accepted = reduced.edits.filter((edit) => edit.status === "accepted");
   const planned = accepted.map((edit) => planEdit(sourceHtml, edit));
   planned.sort((left, right) => right.start - left.start);
   let html = sourceHtml;
@@ -3899,7 +3907,13 @@ function applyAcceptedEdits(sourceHtml, state) {
   }
   return {
     html,
-    appliedEdits: planned.length
+    appliedEdits: planned.length,
+    totalSuggestedEdits: reduced.edits.length,
+    acceptedEdits: accepted.length,
+    openEdits: reduced.edits.filter((edit) => edit.status === "open").length,
+    rejectedEdits: reduced.edits.filter((edit) => edit.status === "rejected").length,
+    deletedEdits: reduced.edits.filter((edit) => edit.status === "deleted").length,
+    skippedEdits: reduced.edits.length - accepted.length
   };
 }
 function planEdit(sourceHtml, edit) {
@@ -3947,12 +3961,21 @@ async function unwrapFile(inputPath, outputPath, options = {}) {
   const sourceBytes = unwrapReviewHtml(reviewHtml);
   if (!options.applyAcceptedEdits) {
     await writeFile4(outputPath, sourceBytes);
-    return {};
+    return { sourceBytes: sourceBytes.byteLength };
   }
   const state = extractReviewState(reviewHtml);
   const result = applyAcceptedEdits(sourceBytes.toString("utf8"), state);
   await writeFile4(outputPath, result.html, "utf8");
-  return { appliedEdits: result.appliedEdits };
+  return {
+    sourceBytes: Buffer.byteLength(result.html, "utf8"),
+    appliedEdits: result.appliedEdits,
+    totalSuggestedEdits: result.totalSuggestedEdits,
+    acceptedEdits: result.acceptedEdits,
+    openEdits: result.openEdits,
+    rejectedEdits: result.rejectedEdits,
+    deletedEdits: result.deletedEdits,
+    skippedEdits: result.skippedEdits
+  };
 }
 
 // src/commands/wrap.ts
@@ -3961,18 +3984,36 @@ async function wrapFile(inputPath, outputPath) {
   const sourceBytes = await readFile5(inputPath);
   const reviewHtml = createReviewHtml(sourceBytes, { sourcePath: inputPath });
   await writeFile5(outputPath, reviewHtml, "utf8");
+  return {
+    sourceBytes: sourceBytes.byteLength,
+    reviewBytes: Buffer.byteLength(reviewHtml, "utf8")
+  };
 }
 
 // src/cli.ts
 async function main(argv = process.argv) {
   try {
-    const command = parseArgs(argv.slice(2));
+    const args = argv.slice(2);
+    const commandName = basename2(argv[1] ?? "html-collab");
+    if (args[0] === "--help" || args[0] === "-h") {
+      process.stdout.write(usage(commandName) + `
+`);
+      return;
+    }
+    if (args[0] === "--version" || args[0] === "-v") {
+      process.stdout.write(packageVersion() + `
+`);
+      return;
+    }
+    const command = parseArgs(args);
     if (command.command === "wrap") {
-      await wrapFile(command.inputPath, command.outputPath);
+      const result2 = await wrapFile(command.inputPath, command.outputPath);
+      writeStatus(`Wrote ${command.outputPath} (${formatBytes(result2.reviewBytes)} review file from ${formatBytes(result2.sourceBytes)} source).`);
       return;
     }
     if (command.command === "merge") {
-      await mergeFiles(command.inputPaths, command.outputPath);
+      const result2 = await mergeFiles(command.inputPaths, command.outputPath);
+      writeStatus(`Merged ${command.inputPaths.length} files into ${command.outputPath} (${formatBytes(result2.reviewBytes)}, ${result2.totalOps} ${plural(result2.totalOps, "operation")}, ${result2.addedOps} new).`);
       return;
     }
     if (command.command === "extract") {
@@ -3982,6 +4023,8 @@ async function main(argv = process.argv) {
       });
       if (!command.outputPath) {
         process.stdout.write(output);
+      } else {
+        writeStatus(`Wrote ${command.outputPath} (${command.format}, ${formatBytes(Buffer.byteLength(output, "utf8"))}).`);
       }
       return;
     }
@@ -3989,14 +4032,18 @@ async function main(argv = process.argv) {
       const output = await skillFile(command.outputPath);
       if (!command.outputPath) {
         process.stdout.write(output);
+      } else {
+        writeStatus(`Wrote ${command.outputPath} (${formatBytes(Buffer.byteLength(output, "utf8"))}).`);
       }
       return;
     }
     const result = await unwrapFile(command.inputPath, command.outputPath, {
       applyAcceptedEdits: command.applyAcceptedEdits
     });
-    if (command.applyAcceptedEdits && result.appliedEdits === 0) {
-      console.warn("No accepted edits to apply; wrote the original source HTML.");
+    if (command.applyAcceptedEdits) {
+      writeStatus(applyEditsStatus(command.outputPath, result));
+    } else {
+      writeStatus(`Wrote ${command.outputPath} (${formatBytes(result.sourceBytes)}, original source HTML).`);
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -4132,6 +4179,8 @@ function isExtractFormat(value) {
 }
 function usage(commandName) {
   return `Usage:
+  ${commandName} --help
+  ${commandName} --version
   ${commandName} wrap report.html --out report.review.html
   ${commandName} merge glen.review.html maya.review.html --out merged.review.html
   ${commandName} extract merged.review.html --format markdown --out review-brief.md
@@ -4141,6 +4190,59 @@ function usage(commandName) {
   ${commandName} unwrap report.review.html --out report.final.html
   ${commandName} unwrap report.review.html --apply-edits --out report.final.html`;
 }
+function writeStatus(message) {
+  console.error(message);
+}
+function applyEditsStatus(outputPath, result) {
+  const applied = result.appliedEdits ?? 0;
+  const skipped = result.skippedEdits ?? 0;
+  const skippedStatus = skipped > 0 ? `; skipped ${formatSkippedEdits(result)}` : "";
+  const output = `Wrote ${outputPath} (${formatBytes(result.sourceBytes)}).`;
+  if (applied === 0) {
+    return `Applied 0 accepted edits${skippedStatus}. ${output}`;
+  }
+  return `Applied ${applied} accepted ${plural(applied, "edit")}${skippedStatus}. ${output}`;
+}
+function formatSkippedEdits(result) {
+  const parts = [
+    countLabel(result.openEdits ?? 0, "open edit"),
+    countLabel(result.rejectedEdits ?? 0, "rejected edit"),
+    countLabel(result.deletedEdits ?? 0, "deleted edit")
+  ].filter(Boolean);
+  return parts.length > 0 ? parts.join(", ") : "0 edits";
+}
+function countLabel(count, label) {
+  return count > 0 ? `${count} ${plural(count, label)}` : undefined;
+}
+function plural(count, singular) {
+  return count === 1 ? singular : `${singular}s`;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const kib = bytes / 1024;
+  if (kib < 1024) {
+    return `${kib.toFixed(kib >= 10 ? 0 : 1)} KB`;
+  }
+  const mib = kib / 1024;
+  return `${mib.toFixed(mib >= 10 ? 0 : 1)} MB`;
+}
+function packageVersion() {
+  let current = dirname3(fileURLToPath2(import.meta.url));
+  while (true) {
+    const candidate = join2(current, "package.json");
+    if (existsSync(candidate)) {
+      const packageJson = JSON.parse(readFileSync(candidate, "utf8"));
+      return packageJson.version ?? "0.0.0";
+    }
+    const parent = dirname3(current);
+    if (parent === current) {
+      return "0.0.0";
+    }
+    current = parent;
+  }
+}
 if (isDirectRun()) {
   await main(process.argv);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-collab",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn any single-file HTML report into a portable, reviewable document. Comments, suggested edits, and deterministic merge — all stored inside the HTML file itself.",
   "type": "module",
   "engines": {