cngkit 1.1.0 → 1.1.1

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.1";
 var defaultApiBaseUrl = "https://curly.ng";
 function resolveApiBaseUrl(options) {
   return options.apiBaseUrl ?? import_node_process.default.env.CNGKIT_API_BASE_URL ?? defaultApiBaseUrl;
@@ -7512,6 +7512,426 @@ function browserOpenCommand(url2) {
   return { command: "xdg-open", args: [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 scrub [path]` - scan for secrets and optionally mask them inline.",
+  "`cngkit knowledges ...` - read the hosted Harness catalog."
+].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 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: "share",
+    aliases: ["share", "sync", "repo-sync"],
+    body: `# cngkit share
+
+Start a real-time repository sync room from the current directory.
+
+## Usage
+
+\`\`\`bash
+cngkit 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: "join",
+    aliases: ["join"],
+    body: `# cngkit join
+
+Join an existing real-time repository sync room in the current directory.
+
+## Usage
+
+\`\`\`bash
+cngkit join <room-code>
+\`\`\`
+
+## Backend Contract
+
+Same transport and filesystem contract as \`cngkit 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 read --help
+cngkit knowledges grep --help
+cngkit knowledges glob --help
+\`\`\`
+
+## 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: \`*\`.
+- \`--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);
@@ -24298,6 +24718,10 @@ async function waitForSessionClose(socket, watcher) {
 // src/commands.ts
 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);
@@ -24692,6 +25116,34 @@ 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" && subtopicName ? `knowledges-${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;
+  }
+  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"