cngkit 1.1.1 → 1.1.3

package/LICENSE

@@ -4,4 +4,4 @@ This software is provided as personal, opinionated Curly.ng tooling.
 
 You can use it, modify it, and share it. If it helps you, support the workshop.
 
-Support: https://curly.ng/donate
+Support: https://curly.ng/support

package/README.md

@@ -1,30 +1,51 @@
 # 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 scrub [path] --yes` rewrites detected secret values inline with `[CNGKIT_SECRET:<detector>:<verified|unverified>]` placeholders.
 - `cngkit knowledges status` prints the remote catalog state.
 - `cngkit knowledges audiences` lists available audience filters.
-- `cngkit knowledges search <query>` runs semantic search against Cloudflare Vectorize.
-- `cngkit knowledges list [query]` lists known subskills.
-- `cngkit knowledges files [query]` lists uploaded catalog files.
-- `cngkit knowledges read <file-path>` reads a catalog file excerpt.
-- `cngkit knowledges grep <pattern>` searches catalog file contents.
-- `cngkit knowledges glob [pattern]` lists catalog files by supported glob pattern.
+- `cngkit knowledges search <query> [--limit n]` runs semantic search against Cloudflare Vectorize (default limit 5).
+- `cngkit knowledges list [query] [--limit n]` lists known subskills (default limit 25).
+- `cngkit knowledges files [query] [--audience id] [--limit n]` lists uploaded catalog files (default limit 25).
+- `cngkit knowledges read <file-path> [--offset n] [--limit n]` reads a catalog file excerpt (default limit 200).
+- `cngkit knowledges grep <pattern> [--path path] [--include glob] [--output-mode content|files_with_matches|count] [--context n] [--case-insensitive]` searches catalog file contents (default mode `content`, default path `/`).
+- `cngkit knowledges glob [pattern] [--path path]` lists catalog files by supported glob pattern (default pattern `**/*.md`, default path `/`).
 - `.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
+```
+
+Global options accepted by every command:
+
+- `--api-base-url <url>` overrides the Curly backend URL (default: `CNGKIT_API_BASE_URL` or `https://curly.ng`).
+- `--version` prints the installed `cngkit` version.
+- `--help` / `-h` prints the progressive help for the current command.
+
+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 +54,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
@@ -49,12 +86,19 @@ cngkit knowledges glob "**/*.md" --path /libraries/lib-cloudflare
 ```
 
 Add `--json` to any `knowledges` command when another tool should consume the
-raw API response. `grep` also accepts `--output-mode <content|files_with_matches|count>`,
-`--include <glob>`, `--context <n>`, and `--case-insensitive`.
+raw API response. `grep` also accepts `--output-mode <content|files_with_matches|count>`
+(default `content`), `--include <glob>` (default `*`), `--context <n>` (default `0`), and
+`--case-insensitive`. Result limits default to `5` for `search` and `25` for `list` and
+`files`; `read` defaults to `200` lines with a backend cap of `2000`, and accepts `--offset`
+for paging.
+
+`read` and `grep` accept shorthand catalog paths: `/libraries/lib-cloudflare/SUBSKILL.md`
+expands to `skills/knowledges/subskills/libraries/lib-cloudflare/SUBSKILL.md`, mirroring the
+Claude `read`/`grep` tool convention.
 
 This package is mostly personal tooling for Curly.ng. It is intentionally opinionated,
 small, and practical rather than a general synchronization platform.
 
 ## License
 
-Beerware. If this helps you, support the workshop: https://curly.ng/donate
+Beerware. If this helps you, support the workshop: https://curly.ng/support

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.3";
 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\`.
@@ -8080,8 +8131,15 @@ function parseJsonRecord(line) {
     return void 0;
   }
 }
+function isJsonRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
 function readRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+  return isJsonRecord(value) ? value : void 0;
 }
 function readString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
@@ -24716,6 +24774,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 +24831,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 +25193,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 +25207,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 +25225,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);