cngkit 1.1.0 → 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.0";
+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;
@@ -7512,6 +7512,477 @@ function browserOpenCommand(url2) {
   return { command: "xdg-open", args: [url2] };
 }
 
+// src/help-specs.ts
+var commandList = [
+  "`cngkit login` - open Curly.ng login.",
+  "`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.",
+  "`search <query>` - semantic search over Cloudflare Vectorize-backed records.",
+  "`list [query]` - list known subskills.",
+  "`files [query]` - list uploaded catalog files.",
+  "`read <file-path>` - Claude-style file read.",
+  "`grep <pattern>` - Claude-style content search.",
+  "`glob [pattern]` - Claude-style file discovery."
+].join("\n");
+var helpTopics = [
+  {
+    title: "cngkit",
+    aliases: ["", "overview", "help"],
+    body: `# cngkit
+
+Curly.ng operator CLI for backend-connected repo sync, secret scrubbing, and Harness knowledges access.
+
+## Usage
+
+\`\`\`bash
+cngkit <command> [options]
+\`\`\`
+
+## Commands
+
+${commandList}
+
+## Progressive Help
+
+\`\`\`bash
+cngkit <command> --help
+cngkit coderoom --help
+cngkit coderoom <subcommand> --help
+cngkit knowledges --help
+cngkit knowledges <subcommand> --help
+\`\`\`
+
+The CLI intentionally prints plain Markdown or line-oriented text with no color-only state, tables that require terminal width, or hidden interactive prompts. Add \`--json\` to read-only knowledges commands when another agent or tool needs structured backend data.
+
+## Backend
+
+Default API: \`https://curly.ng\`
+
+Override with:
+
+\`\`\`bash
+cngkit --api-base-url <url> ...
+CNGKIT_API_BASE_URL=<url> cngkit ...
+\`\`\`
+`
+  },
+  {
+    title: "login",
+    aliases: ["login"],
+    body: `# cngkit login
+
+Open Curly.ng login in a browser. In headless environments, print the URL so an agent can surface it to the operator.
+
+## Usage
+
+\`\`\`bash
+cngkit login
+\`\`\`
+
+## Output Contract
+
+- First line names the login URL being opened.
+- If no local browser opener exists, the CLI prints a direct URL.
+- No credentials are printed or persisted by this command.
+`
+  },
+  {
+    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 coderoom share [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.
+
+## Filesystem Contract
+
+- Preserves \`.git/\`.
+- Preserves files ignored by the repo's \`.gitignore\`.
+- Sends regular files as base64 payloads in the sync protocol.
+
+## Output Contract
+
+- Prints room code, repo root, peer id, backend health, and concise sync events.
+- Keeps running until the socket closes or the process receives a termination signal.
+`
+  },
+  {
+    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 coderoom join <room-code>
+\`\`\`
+
+## Backend Contract
+
+Same transport and filesystem contract as \`cngkit coderoom share\`. The supplied room code selects the Durable Object room.
+
+## Output Contract
+
+- Prints backend health, room code, repo root, peer id, and concise sync events.
+- Missing room code exits with a usage error.
+`
+  },
+  {
+    title: "scrub",
+    aliases: ["scrub"],
+    body: `# cngkit scrub
+
+Scan a file or directory for secrets with TruffleHog. Report-only is the default. Inline masking requires \`--yes\`.
+
+## Usage
+
+\`\`\`bash
+cngkit scrub [path]
+cngkit scrub [path] --yes
+\`\`\`
+
+## Requirements
+
+- \`trufflehog\` must be available on \`PATH\`.
+
+## Safety Contract
+
+- Default mode does not rewrite files.
+- \`--yes\` rewrites detected secret values inline with \`[CNGKIT_SECRET:<detector>:<verified|unverified>]\` placeholders.
+- \`--mask\` is accepted as a compatibility alias, but still requires \`--yes\`.
+- Raw and redacted secret values are never printed in the report.
+`
+  },
+  {
+    title: "knowledges",
+    aliases: ["knowledges", "knowledge"],
+    body: `# cngkit knowledges
+
+Read the hosted Harness knowledges catalog from the Curly backend. These commands are read-only and use the generated \`@cng/client\` SDK against public backend routes.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges <subcommand> [options]
+\`\`\`
+
+## Subcommands
+
+${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.
+- \`read\` prints file content with no wrapper before any truncation note.
+- \`grep --output-mode content\` prints \`path:line\` blocks.
+- \`grep --output-mode files_with_matches\` and \`glob\` print one path per line.
+- \`--json\` prints the typed backend data payload for machine consumption.
+`
+  },
+  {
+    title: "knowledges status",
+    aliases: ["knowledges-status", "status"],
+    body: `# cngkit knowledges status
+
+Print remote Harness catalog state from \`GET /api/harness/knowledges/catalog\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges status [--json]
+\`\`\`
+
+## Output Contract
+
+- Text mode prints catalog name, file count, blob count, Vectorize binding, and latest run when present.
+- \`--json\` prints the backend data payload.
+`
+  },
+  {
+    title: "knowledges audiences",
+    aliases: ["knowledges-audiences", "audiences"],
+    body: `# cngkit knowledges audiences
+
+List valid audience filters from \`GET /api/harness/knowledges/audiences\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges audiences [--json]
+\`\`\`
+
+Use this before \`cngkit knowledges files --audience <id>\`.
+`
+  },
+  {
+    title: "knowledges search",
+    aliases: ["knowledges-search", "search"],
+    body: `# cngkit knowledges search
+
+Run semantic search against the Cloudflare Vectorize-backed Harness index.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges search <query> [--limit <n>] [--json]
+\`\`\`
+
+## Defaults
+
+- \`--limit\`: \`5\`
+
+## Example
+
+\`\`\`bash
+cngkit knowledges search "cloudflare backend" --limit 3
+\`\`\`
+`
+  },
+  {
+    title: "knowledges list",
+    aliases: ["knowledges-list", "list"],
+    body: `# cngkit knowledges list
+
+List known subskills from \`GET /api/harness/knowledges/subskills\`, optionally filtered locally by query.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges list [query] [--limit <n>] [--json]
+\`\`\`
+
+## Defaults
+
+- \`--limit\`: \`25\`
+`
+  },
+  {
+    title: "knowledges files",
+    aliases: ["knowledges-files", "files"],
+    body: `# cngkit knowledges files
+
+List uploaded catalog files from \`GET /api/harness/knowledges/files\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges files [query] [--audience <id>] [--limit <n>] [--json]
+\`\`\`
+
+## Defaults
+
+- \`--limit\`: \`25\`
+- \`--audience\`: omitted
+
+Run \`cngkit knowledges audiences\` to discover supported audience ids.
+`
+  },
+  {
+    title: "knowledges read",
+    aliases: ["knowledges-read", "read"],
+    body: `# cngkit knowledges read
+
+Claude-style read tool for hosted Harness catalog files. Backed by \`GET /api/harness/filesystem/read\` and \`HarnessReadQuerySchema\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges read <file-path> [--offset <n>] [--limit <n>] [--json]
+\`\`\`
+
+## Inputs
+
+- \`file-path\`: normalized catalog path. Shorthand paths such as \`/libraries/lib-cloudflare/SUBSKILL.md\` are expanded to \`skills/knowledges/subskills/libraries/lib-cloudflare/SUBSKILL.md\`.
+- \`--offset\`: zero-based starting line. Default: \`0\`.
+- \`--limit\`: maximum lines. Default in CLI: \`200\`. Backend max: \`2000\`.
+
+## Output Contract
+
+- Text mode prints only the returned file content first.
+- If truncated, a final bracketed truncation note is printed after the content.
+- \`--json\` prints \`{ file_path, content, total_lines, offset, limit, truncated }\`.
+
+## Example
+
+\`\`\`bash
+cngkit knowledges read /libraries/lib-cloudflare/SUBSKILL.md --limit 80
+\`\`\`
+`
+  },
+  {
+    title: "knowledges grep",
+    aliases: ["knowledges-grep", "grep"],
+    body: `# cngkit knowledges grep
+
+Claude-style grep tool for hosted Harness catalog files. Backed by \`GET /api/harness/filesystem/grep\` and \`HarnessGrepQuerySchema\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges grep <pattern> [--path <path>] [--include <glob>] [--output-mode <mode>] [--context <n>] [--case-insensitive] [--json]
+\`\`\`
+
+## Inputs
+
+- \`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\`.
+
+## Output Contract
+
+- \`content\`: prints blocks as \`file_path:line_number\`, optional context lines, then \`> matching line\`.
+- \`files_with_matches\`: prints one matching file path per line.
+- \`count\`: prints \`file_path: match_count\` lines.
+- \`--json\` prints the typed backend response union.
+
+## Examples
+
+\`\`\`bash
+cngkit knowledges grep Cloudflare --path /libraries/lib-cloudflare --output-mode files_with_matches
+cngkit knowledges grep "Vectorize|D1" --path /libraries/lib-cloudflare --context 2
+\`\`\`
+`
+  },
+  {
+    title: "knowledges glob",
+    aliases: ["knowledges-glob", "glob"],
+    body: `# cngkit knowledges glob
+
+Claude-style glob tool for hosted Harness catalog files. Backed by \`GET /api/harness/filesystem/glob\` and \`HarnessGlobQuerySchema\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges glob [pattern] [--path <path>] [--json]
+\`\`\`
+
+## Inputs
+
+- \`pattern\`: supported glob pattern. CLI default: \`**/*.md\`.
+- \`--path\`: catalog path prefix. Default: \`/\`.
+
+## Supported Patterns
+
+- \`**/*.md\`
+- \`**/*.SUBSKILL.md\`
+- \`**/SKILL.md\`
+- \`*.md\`
+- \`*.SUBSKILL.md\`
+- \`SKILL.md\`
+
+## Output Contract
+
+- Text mode prints one file path per line.
+- If truncated, a final bracketed truncation note is printed.
+- \`--json\` prints \`{ files, total_files, truncated }\`.
+
+## Example
+
+\`\`\`bash
+cngkit knowledges glob "**/*.md" --path /libraries/lib-cloudflare
+\`\`\`
+`
+  }
+];
+var helpTopicByAlias = /* @__PURE__ */ new Map();
+for (const topic of helpTopics) {
+  for (const alias of topic.aliases) {
+    helpTopicByAlias.set(alias, topic);
+  }
+}
+function formatCngkitHelp(topicName) {
+  const normalizedTopicName = normalizeHelpTopicName(topicName);
+  return (helpTopicByAlias.get(normalizedTopicName) ?? helpTopicByAlias.get(""))?.body.trim() ?? "";
+}
+function formatKnowledgesHelp(topicName) {
+  const normalizedTopicName = normalizeHelpTopicName(topicName);
+  const topicKey = normalizedTopicName ? `knowledges-${normalizedTopicName}` : "knowledges";
+  return formatCngkitHelp(topicKey);
+}
+function normalizeHelpTopicName(value) {
+  return value?.trim().toLowerCase().replace(/\s+/g, "-") ?? "";
+}
+
 // src/scrub/masker.ts
 var import_promises = __toESM(require("fs/promises"), 1);
 var import_node_path = __toESM(require("path"), 1);
@@ -24296,8 +24767,23 @@ 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") {
+    output.info(formatKnowledgesHelp(subcommandArgs[0]));
+    return;
+  }
   switch (subcommand) {
     case "status":
       return runKnowStatusCommand(options, output, dependencies);
@@ -24338,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);
@@ -24692,6 +25178,39 @@ function handleFatalError(error51) {
   consoleOutput.error(formatError2(error51));
   import_node_process5.default.exitCode = 1;
 }
+function printMarkdownHelpIfRequested(argv) {
+  const commandName = argv[2];
+  if (commandName === void 0 || commandName === "--help" || commandName === "-h") {
+    consoleOutput.info(formatCngkitHelp());
+    return true;
+  }
+  if (commandName === "help") {
+    const [topicName, subtopicName] = argv.slice(3);
+    const topic = (topicName === "knowledges" || topicName === "coderoom") && subtopicName ? `${topicName}-${subtopicName}` : topicName;
+    consoleOutput.info(formatCngkitHelp(topic));
+    return true;
+  }
+  const commandArgs = argv.slice(3);
+  const helpIndex = commandArgs.findIndex((argument) => argument === "--help" || argument === "-h");
+  if (helpIndex < 0) {
+    return false;
+  }
+  if (commandName === "knowledges") {
+    const topic = commandArgs.find((argument, index) => index !== helpIndex && !argument.startsWith("-"));
+    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;
+}
+if (printMarkdownHelpIfRequested(import_node_process5.default.argv)) {
+  import_node_process5.default.exit(0);
+}
 cli.option(
   "--api-base-url <url>",
   "Curly API base URL. Default: CNGKIT_API_BASE_URL or https://curly.ng"
@@ -24699,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);