cngkit 1.0.0 → 1.1.0

package/README.md

@@ -1,18 +1,27 @@
 # cngkit
 
-Opinionated Curly.ng CLI kit for repo sync and website tooling.
+Opinionated Curly.ng CLI kit for repo sync, Harness knowledges, and website tooling.
 
 ```bash
 npx cngkit
 ```
 
-The first MVP provides a real-time repository sync room:
+The CLI provides a real-time repository sync room 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 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.
+- `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.
 - `.git/` and files ignored by the repo's `.gitignore` are not synced.
 - Later changes override earlier changes for the MVP conflict rule.
 
@@ -24,6 +33,25 @@ brew install trufflehog
 
 Inline masking is intentionally gated behind `--yes` because it rewrites files in place.
 
+## Harness Knowledges
+
+The `knowledges` command group reads the Cloudflare-backed Harness catalog from the
+Curly API. These commands are read-only:
+
+```bash
+cngkit knowledges status
+cngkit knowledges audiences
+cngkit knowledges search "cloudflare backend" --limit 3
+cngkit knowledges files "vector search" --audience builders
+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
+```
+
+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`.
+
 This package is mostly personal tooling for Curly.ng. It is intentionally opinionated,
 small, and practical rather than a general synchronization platform.
 

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.0.0";
+var packageVersion = "1.1.0";
 var defaultApiBaseUrl = "https://curly.ng";
 function resolveApiBaseUrl(options) {
   return options.apiBaseUrl ?? import_node_process.default.env.CNGKIT_API_BASE_URL ?? defaultApiBaseUrl;
@@ -24296,6 +24296,31 @@ async function waitForSessionClose(socket, watcher) {
 }
 
 // src/commands.ts
+async function runKnowledgesCommand(args, options, output, dependencies) {
+  const [subcommand, ...subcommandArgs] = args ?? [];
+  switch (subcommand) {
+    case "status":
+      return runKnowStatusCommand(options, output, dependencies);
+    case "audiences":
+      return runKnowAudiencesCommand(options, output, dependencies);
+    case "search":
+      return runKnowSearchCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "list":
+      return runKnowListCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "files":
+      return runKnowFilesCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "read":
+      return runKnowReadCommand(subcommandArgs[0], options, output, dependencies);
+    case "grep":
+      return runKnowGrepCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "glob":
+      return runKnowGlobCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    default:
+      throw new Error(
+        "Missing knowledges command. Usage: cngkit knowledges <status|audiences|search|list|files|read|grep|glob>"
+      );
+  }
+}
 async function runLoginCommand(options, output) {
   const loginUrl = new URL("/login", resolveApiBaseUrl(options));
   const loginUrlString = loginUrl.toString();
@@ -24344,6 +24369,172 @@ async function runScrubCommand(targetPath, options, output, dependencies) {
     output.info(`Skipped ${result.skippedFindings} finding(s) outside the scrub root.`);
   }
 }
+async function runKnowStatusCommand(options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.getCatalog();
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const latestRun = response.data.latestRun;
+  const lines = [
+    `Catalog: ${response.data.name}`,
+    `Files: ${response.data.files}`,
+    `Blobs: ${response.data.blobs}`,
+    `Vectorize: ${response.data.vectorize.index} (${response.data.vectorize.binding})`
+  ];
+  if (latestRun) {
+    lines.push(`Latest run: ${latestRun.status} (${latestRun.id})`);
+    if (latestRun.updated_at) {
+      lines.push(`Updated: ${latestRun.updated_at}`);
+    }
+  } else {
+    lines.push("Latest run: none");
+  }
+  output.info(lines.join("\n"));
+}
+async function runKnowAudiencesCommand(options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.listAudiences();
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const lines = response.data.audiences.flatMap((audience) => [
+    `${audience.id} - ${audience.label}`,
+    `  ${singleLine(audience.help)}`
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : "No audiences available.");
+}
+async function runKnowSearchCommand(query, options, output, dependencies) {
+  if (!query) {
+    throw new Error("Missing search query. Usage: cngkit knowledges search <query>");
+  }
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.search(query, coerceLimit(options.limit, 5));
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const lines = response.data.results.flatMap((result, index) => [
+    `${index + 1}. ${result.title} (${result.subskillName})`,
+    `   score ${result.score.toFixed(3)} | ${result.path}`,
+    `   ${singleLine(result.description || result.contentPreview)}`
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : `No results for "${query}".`);
+}
+async function runKnowListCommand(query, options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.listSubskills();
+  const limit = coerceLimit(options.limit, 25);
+  const normalizedQuery = query?.toLowerCase();
+  const subskills = response.data.subskills.filter((subskill) => {
+    if (!normalizedQuery) {
+      return true;
+    }
+    return [subskill.name, subskill.title, subskill.description, subskill.type].join(" ").toLowerCase().includes(normalizedQuery);
+  }).slice(0, limit);
+  if (options.json) {
+    output.info(formatJson({ subskills, total: subskills.length }));
+    return;
+  }
+  const lines = subskills.flatMap((subskill) => [
+    `${subskill.name} [${subskill.type}]`,
+    `  ${subskill.title} | files ${subskill.fileCount} | rating ${subskill.rating}`,
+    `  ${singleLine(subskill.description)}`
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : "No matching subskills.");
+}
+async function runKnowFilesCommand(query, options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.listFiles({
+    query,
+    audience: normalizeAudienceId(options.audience),
+    limit: coerceLimit(options.limit, 25)
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const lines = response.data.files.map((file2) => {
+    const title = file2.display_title ?? file2.title ?? file2.subskill_name ?? "Untitled";
+    return `${file2.path}
+  ${title}`;
+  });
+  output.info(lines.length > 0 ? lines.join("\n") : "No matching files.");
+}
+async function runKnowReadCommand(filePath, options, output, dependencies) {
+  if (!filePath) {
+    throw new Error("Missing file_path. Usage: cngkit knowledges read <file_path>");
+  }
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.read({
+    filePath: normalizeCatalogPath(filePath),
+    offset: coerceOptionalNumber(options.offset),
+    limit: coerceLimit(options.limit, 200, 2e3)
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  output.info(response.data.content);
+  if (response.data.truncated) {
+    output.info(
+      `[truncated: showing ${response.data.limit} lines from offset ${response.data.offset} of ${response.data.total_lines}]`
+    );
+  }
+}
+async function runKnowGrepCommand(pattern, options, output, dependencies) {
+  if (!pattern) {
+    throw new Error("Missing pattern. Usage: cngkit knowledges grep <pattern>");
+  }
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.grep({
+    pattern,
+    path: normalizeCatalogPath(options.path ?? "/"),
+    include: options.include ?? "*",
+    mode: normalizeGrepMode(options.outputMode),
+    context: coerceLimit(options.context, 0, 20),
+    ignoreCase: options.caseInsensitive === true
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  if (response.data.mode === "files_with_matches") {
+    output.info(
+      response.data.files.length > 0 ? response.data.files.join("\n") : `No files matched "${pattern}".`
+    );
+    return;
+  }
+  if (response.data.mode === "count") {
+    const lines2 = response.data.counts.map((count) => `${count.file_path}: ${count.match_count}`);
+    output.info(lines2.length > 0 ? lines2.join("\n") : `No matches for "${pattern}".`);
+    return;
+  }
+  const lines = response.data.matches.flatMap((match) => [
+    `${match.file_path}:${match.line_number}`,
+    ...match.context_before.map((line) => `  ${line}`),
+    `> ${match.line}`,
+    ...match.context_after.map((line) => `  ${line}`)
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : `No matches for "${pattern}".`);
+}
+async function runKnowGlobCommand(pattern, options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.glob({
+    pattern: pattern ?? "**/*.md",
+    path: normalizeCatalogPath(options.path ?? "/")
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  output.info(response.data.files.length > 0 ? response.data.files.join("\n") : "No matching files.");
+  if (response.data.truncated) {
+    output.info(`[truncated: ${response.data.total_files} total files]`);
+  }
+}
 async function printBackendStatus(options, output) {
   const health = await readBackendHealth(options);
   output.info(health.ok ? `API: ${health.service} ready` : `API: unavailable (${health.message})`);
@@ -24366,6 +24557,121 @@ function formatScrubReport(findings) {
   }
   return lines.join("\n");
 }
+function createKnowledgesApi(options) {
+  const client = createCngApiClient(options);
+  return {
+    getCatalog: () => client.harnessKnowledges.getHarnessKnowledgesCatalog(),
+    listAudiences: () => client.harnessKnowledges.listHarnessKnowledgesAudiences(),
+    search: (query, limit) => client.harnessKnowledges.searchHarnessKnowledges({
+      q: query,
+      limit
+    }),
+    listSubskills: () => client.harnessKnowledges.listHarnessKnowledgesSubskills(),
+    listFiles: ({ query, audience, limit }) => client.harnessKnowledges.listHarnessSubskillAssets({
+      ...query ? { q: query } : {},
+      ...audience ? { audience } : {},
+      limit
+    }),
+    read: ({ filePath, offset, limit }) => client.harnessFilesystem.getHarnessFilesystemRead({
+      file_path: filePath,
+      offset,
+      limit
+    }),
+    grep: ({ pattern, path: path5, include, mode, context, ignoreCase }) => client.harnessFilesystem.getHarnessFilesystemGrep({
+      pattern,
+      path: path5,
+      include,
+      output_mode: mode,
+      context,
+      case_insensitive: ignoreCase ? "true" : void 0
+    }),
+    glob: ({ pattern, path: path5 }) => client.harnessFilesystem.getHarnessFilesystemGlob({
+      pattern,
+      path: path5
+    })
+  };
+}
+function coerceLimit(value, defaultValue, maxValue = 100) {
+  const normalizedValue = coerceOptionalNumber(value);
+  if (normalizedValue === void 0 || Number.isNaN(normalizedValue)) {
+    return defaultValue;
+  }
+  return Math.max(defaultValue === 0 ? 0 : 1, Math.min(maxValue, Math.trunc(normalizedValue)));
+}
+function coerceOptionalNumber(value) {
+  if (value === void 0 || value === "") {
+    return void 0;
+  }
+  return Number(value);
+}
+function normalizeAudienceId(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  switch (value) {
+    case "all":
+    case "operators":
+    case "builders":
+    case "researchers":
+    case "agent-makers":
+      return value;
+    default:
+      throw new Error(
+        `Unknown audience "${value}". Run cngkit knowledges audiences to see supported values.`
+      );
+  }
+}
+function normalizeGrepMode(value) {
+  if (value === void 0) {
+    return "content";
+  }
+  switch (value) {
+    case "content":
+    case "files_with_matches":
+    case "count":
+      return value;
+    default:
+      throw new Error("Unknown grep mode. Use one of: content, files_with_matches, count.");
+  }
+}
+function singleLine(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function formatJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+function optionalJoinedArgument(values) {
+  return values.length > 0 ? values.join(" ") : void 0;
+}
+function normalizeCatalogPath(value) {
+  const trimmed = value.trim();
+  if (trimmed === "/" || trimmed === "") {
+    return "/";
+  }
+  const relativePath = trimmed.replace(/^\/+/, "");
+  if (relativePath.startsWith("skills/knowledges/")) {
+    return relativePath;
+  }
+  const [firstSegment, ...restSegments] = relativePath.split("/");
+  if (!firstSegment || restSegments.length === 0) {
+    return relativePath;
+  }
+  switch (firstSegment) {
+    case "concepts":
+    case "domains":
+    case "formats":
+    case "languages":
+    case "libraries":
+    case "patterns":
+    case "platforms":
+    case "procedures":
+    case "protocols":
+    case "tools":
+      return `skills/knowledges/subskills/${firstSegment}/${restSegments.join("/")}`;
+    default:
+      return relativePath;
+  }
+}
 
 // src/output.ts
 var consoleOutput = {
@@ -24402,6 +24708,9 @@ cli.command("join <room-code>", "Join a real-time repo sync room in the current
 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);
 });
+cli.command("knowledges [...args]", "Use the Cloudflare-backed Harness knowledges catalog").option("--limit <n>", "Maximum results").option("--audience <id>", "Audience filter").option("--offset <n>", "Starting line offset").option("--path <path>", "Catalog path prefix").option("--include <glob>", "Filename include filter").option("--output-mode <mode>", "Output mode: content, files_with_matches, count").option("--context <n>", "Context lines around content matches").option("--case-insensitive", "Case-insensitive search").option("--json", "Print raw JSON").action((args, options) => {
+  void runKnowledgesCommand(args, options, consoleOutput).catch(handleFatalError);
+});
 try {
   cli.parse(import_node_process5.default.argv);
 } catch (error51) {