cngkit 1.1.1 → 1.1.2

package/README.md

@@ -1,17 +1,17 @@
 # cngkit
 
-Opinionated Curly.ng CLI kit for repo sync, Harness knowledges, and website tooling.
+Opinionated Curly.ng CLI kit for Coderoom collaboration, Harness knowledges, and website tooling.
 
 ```bash
 npx cngkit
 ```
 
-The CLI provides a real-time repository sync room and a terminal front door to
+The CLI provides Coderoom collaboration, secret scrubbing, and a terminal front door to
 the Cloudflare-backed Harness knowledges catalog:
 
-- `cngkit share` starts a room from the current directory.
-- `cngkit join <room-code>` joins another machine to that room.
 - `cngkit login` opens Curly.ng login in a browser, or prints the URL in headless environments.
+- `cngkit coderoom share [room-code]` starts a live shared code room from the current directory.
+- `cngkit coderoom join <room-code>` joins another developer's shared code room.
 - `cngkit scrub [path]` scans a file or directory with TruffleHog and prints a redacted report.
 - `cngkit scrub [path] --yes` rewrites detected secret values inline with `CNGKIT_SECRET` placeholders.
 - `cngkit knowledges status` prints the remote catalog state.
@@ -25,6 +25,21 @@ the Cloudflare-backed Harness knowledges catalog:
 - `.git/` and files ignored by the repo's `.gitignore` are not synced.
 - Later changes override earlier changes for the MVP conflict rule.
 
+Help is baked into the CLI as Markdown with progressive disclosure:
+
+```bash
+cngkit --help
+cngkit scrub --help
+cngkit knowledges --help
+cngkit knowledges read --help
+cngkit knowledges grep --help
+cngkit knowledges glob --help
+```
+
+The canonical CLI spec lives at `docs/superpowers/specs/2026-06-25-cngkit-cli-spec.md`
+in the repository. The baked help source lives in `src/help-specs.ts`; keep both
+aligned when changing command behavior.
+
 `scrub` requires the `trufflehog` binary on `PATH`. On macOS, install it with:
 
 ```bash
@@ -33,6 +48,22 @@ brew install trufflehog
 
 Inline masking is intentionally gated behind `--yes` because it rewrites files in place.
 
+## Coderoom
+
+Coderoom is for quickly uniting developers around one working tree. One developer starts
+a room, another joins it, and the Curly backend relays file changes through the
+`/api/cng/sync/:roomCode` WebSocket room.
+
+```bash
+cngkit coderoom share
+cngkit coderoom join <room-code>
+```
+
+The frontend helper lives at `/coderoom`. It presents Coderoom as a Drive-like
+shared workspace: a room code acts like a share link, connected machines act like
+collaborators, and file events act like the activity stream. Current Coderoom
+rooms are live relays, not durable cloud storage.
+
 ## Harness Knowledges
 
 The `knowledges` command group reads the Cloudflare-backed Harness catalog from the

package/dist/cli.cjs

@@ -7443,7 +7443,7 @@ var logging;
 // src/config.ts
 var import_node_crypto = require("crypto");
 var import_node_process = __toESM(require("process"), 1);
-var packageVersion = "1.1.1";
+var packageVersion = "1.1.2";
 var defaultApiBaseUrl = "https://curly.ng";
 function resolveApiBaseUrl(options) {
   return options.apiBaseUrl ?? import_node_process.default.env.CNGKIT_API_BASE_URL ?? defaultApiBaseUrl;
@@ -7515,11 +7515,14 @@ function browserOpenCommand(url2) {
 // src/help-specs.ts
 var commandList = [
   "`cngkit login` - open Curly.ng login.",
-  "`cngkit share [room-code]` - start a live repo sync room.",
-  "`cngkit join <room-code>` - join a live repo sync room.",
+  "`cngkit coderoom ...` - unite developers in a live shared code room.",
   "`cngkit scrub [path]` - scan for secrets and optionally mask them inline.",
   "`cngkit knowledges ...` - read the hosted Harness catalog."
 ].join("\n");
+var coderoomCommandList = [
+  "`share [room-code]` - start a live room from the current directory.",
+  "`join <room-code>` - join another developer's live room from the current directory."
+].join("\n");
 var knowledgesCommandList = [
   "`status` - print remote catalog state.",
   "`audiences` - list valid audience filters.",
@@ -7552,6 +7555,8 @@ ${commandList}
 
 \`\`\`bash
 cngkit <command> --help
+cngkit coderoom --help
+cngkit coderoom <subcommand> --help
 cngkit knowledges --help
 cngkit knowledges <subcommand> --help
 \`\`\`
@@ -7591,16 +7596,51 @@ cngkit login
 `
   },
   {
-    title: "share",
-    aliases: ["share", "sync", "repo-sync"],
-    body: `# cngkit share
+    title: "coderoom",
+    aliases: ["coderoom", "code-room", "repo-sync"],
+    body: `# cngkit coderoom
+
+Coderoom is the fast way to unite developers around one working tree. It gives a pair or team a temporary shared room over the Curly backend so one developer can share local file changes and another can join from their own machine.
+
+It is intentionally closer to a Drive-like project room than a raw socket command: the room code is the shared folder link, each connected machine is a collaborator, and the file stream is the activity feed. The browser experience at \`/coderoom\` provides the helper surface for copying commands and explaining the room model.
+
+## Usage
+
+\`\`\`bash
+cngkit coderoom <subcommand> [options]
+\`\`\`
+
+## Subcommands
+
+${coderoomCommandList}
+
+## Common Flow
+
+\`\`\`bash
+cngkit coderoom share
+cngkit coderoom join <room-code>
+\`\`\`
+
+## Backend Contract
+
+- Connects to \`/api/cng/sync/:roomCode\` on the configured Curly backend.
+- Uses WebSocket transport backed by the \`CngSyncRoom\` Durable Object.
+- Sends an initial snapshot, then file and delete events.
+- Last received change wins.
+- Current rooms are live relays, not durable cloud storage. The Drive-like frontend is the collaboration shell around that live primitive.
+`
+  },
+  {
+    title: "coderoom share",
+    aliases: ["coderoom-share"],
+    body: `# cngkit coderoom share
 
 Start a real-time repository sync room from the current directory.
 
 ## Usage
 
 \`\`\`bash
-cngkit share [room-code]
+cngkit coderoom share [room-code]
 \`\`\`
 
 ## Backend Contract
@@ -7623,21 +7663,21 @@ cngkit share [room-code]
 `
   },
   {
-    title: "join",
-    aliases: ["join"],
-    body: `# cngkit join
+    title: "coderoom join",
+    aliases: ["coderoom-join"],
+    body: `# cngkit coderoom join
 
 Join an existing real-time repository sync room in the current directory.
 
 ## Usage
 
 \`\`\`bash
-cngkit join <room-code>
+cngkit coderoom join <room-code>
 \`\`\`
 
 ## Backend Contract
 
-Same transport and filesystem contract as \`cngkit share\`. The supplied room code selects the Durable Object room.
+Same transport and filesystem contract as \`cngkit coderoom share\`. The supplied room code selects the Durable Object room.
 
 ## Output Contract
 
@@ -7691,11 +7731,21 @@ ${knowledgesCommandList}
 ## Progressive Help
 
 \`\`\`bash
+cngkit knowledges <subcommand> --help
 cngkit knowledges read --help
 cngkit knowledges grep --help
 cngkit knowledges glob --help
 \`\`\`
 
+## Common Examples
+
+\`\`\`bash
+cngkit knowledges search "cloudflare backend" --limit 3
+cngkit knowledges read /libraries/lib-cloudflare/SUBSKILL.md --limit 80
+cngkit knowledges grep Cloudflare --path /libraries/lib-cloudflare --output-mode files_with_matches
+cngkit knowledges glob "**/*.md" --path /libraries/lib-cloudflare
+\`\`\`
+
 ## AI-Friendly Output
 
 - Default output is line-oriented and intended to be directly usable by agents.
@@ -7853,6 +7903,7 @@ cngkit knowledges grep <pattern> [--path <path>] [--include <glob>] [--output-mo
 - \`pattern\`: JavaScript regular expression source.
 - \`--path\`: catalog path prefix. Default: \`/\`.
 - \`--include\`: filename include filter. Default: \`*\`.
+- Modes: content, files_with_matches, or count.
 - \`--output-mode\`: \`content\`, \`files_with_matches\`, or \`count\`. Default: \`content\`.
 - \`--context\`: context lines around content matches. Default: \`0\`. Backend max: \`20\`.
 - \`--case-insensitive\`: maps to backend \`case_insensitive=true\`.
@@ -24716,6 +24767,17 @@ async function waitForSessionClose(socket, watcher) {
 }
 
 // src/commands.ts
+async function runCoderoomCommand(args, options, output) {
+  const [subcommand, ...subcommandArgs] = args ?? [];
+  switch (subcommand) {
+    case "share":
+      return runShareCommand(subcommandArgs[0], options, output);
+    case "join":
+      return runJoinCommand(subcommandArgs[0], options, output);
+    default:
+      throw new Error("Missing coderoom command. Usage: cngkit coderoom <share|join>");
+  }
+}
 async function runKnowledgesCommand(args, options, output, dependencies) {
   const [subcommand, ...subcommandArgs] = args ?? [];
   if (subcommand === void 0 || subcommand === "help") {
@@ -24762,7 +24824,7 @@ async function runShareCommand(roomCode, options, output) {
 }
 async function runJoinCommand(roomCode, options, output) {
   if (!roomCode) {
-    throw new Error("Missing room code. Usage: cngkit join <room-code>");
+    throw new Error("Missing room code. Usage: cngkit coderoom join <room-code>");
   }
   await printBackendStatus(options, output);
   await runSyncSession("join", roomCode, options, output);
@@ -25124,7 +25186,7 @@ function printMarkdownHelpIfRequested(argv) {
   }
   if (commandName === "help") {
     const [topicName, subtopicName] = argv.slice(3);
-    const topic = topicName === "knowledges" && subtopicName ? `knowledges-${subtopicName}` : topicName;
+    const topic = (topicName === "knowledges" || topicName === "coderoom") && subtopicName ? `${topicName}-${subtopicName}` : topicName;
     consoleOutput.info(formatCngkitHelp(topic));
     return true;
   }
@@ -25138,6 +25200,11 @@ function printMarkdownHelpIfRequested(argv) {
     consoleOutput.info(formatKnowledgesHelp(topic));
     return true;
   }
+  if (commandName === "coderoom") {
+    const topic = commandArgs.find((argument, index) => index !== helpIndex && !argument.startsWith("-"));
+    consoleOutput.info(formatCngkitHelp(topic ? `coderoom-${topic}` : "coderoom"));
+    return true;
+  }
   consoleOutput.info(formatCngkitHelp(commandName));
   return true;
 }
@@ -25151,11 +25218,8 @@ cli.option(
 cli.command("login", "Open Curly login in your browser").action((options) => {
   void runLoginCommand(options, consoleOutput).catch(handleFatalError);
 });
-cli.command("share [room-code]", "Start a real-time repo sync room from the current directory").action((roomCode, options) => {
-  void runShareCommand(roomCode, options, consoleOutput).catch(handleFatalError);
-});
-cli.command("join <room-code>", "Join a real-time repo sync room in the current directory").action((roomCode, options) => {
-  void runJoinCommand(roomCode, options, consoleOutput).catch(handleFatalError);
+cli.command("coderoom [...args]", "Start or join a real-time repo sync room").action((args, options) => {
+  void runCoderoomCommand(args, options, consoleOutput).catch(handleFatalError);
 });
 cli.command("scrub [path]", "Scan for secrets with TruffleHog and optionally mask them inline").option("--mask", "Compatibility alias for inline scrubbing; --yes is still required").option("--yes", "Confirm and run inline scrubbing").action((targetPath, options) => {
   void runScrubCommand(targetPath, options, consoleOutput).catch(handleFatalError);