cngkit 1.1.6 → 1.1.8

package/README.md

@@ -1,127 +1,297 @@
 # cngkit
 
-Opinionated Curly.ng CLI kit for Coderoom collaboration, Harness knowledges, and website tooling.
+[![npm version](https://img.shields.io/npm/v/cngkit.svg)](https://www.npmjs.com/package/cngkit)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-339933)](https://nodejs.org/)
+
+Curly.ng's operator CLI for shared code rooms, safe local cleanup, local agent transcript
+inspection, and terminal access to the hosted Harness knowledge catalog.
+
+`cngkit` is built for developers and AI agents who need practical commands that work
+well in terminals, scripts, and coding assistants. Human-facing status lines use Ink
+styling when the terminal supports color. Data-heavy output stays plain and easy to pipe.
+
+## Quick Start
+
+Run it without installing:
 
 ```bash
-npx cngkit
+npx --yes cngkit@latest --help
 ```
 
-The CLI provides Coderoom collaboration, secret scrubbing, and a terminal front door to
-the Cloudflare-backed Harness knowledges catalog:
+Or install it globally:
 
-- `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:<detector>:<verified|unverified>]` placeholders.
-- `cngkit transcripts list [--source all|codex|claude] [--limit n]` lists recent local Claude/Codex transcript files.
-- `cngkit transcripts read <path-or-session-id> [--limit n]` prints normalized user/assistant transcript entries.
-- `cngkit transcripts grep <query> [--limit n] [--file-limit n]` searches recent local transcript entries.
-- `cngkit knowledges status` prints the remote catalog state.
-- `cngkit knowledges audiences` lists available audience filters.
-- `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.
+```bash
+npm install -g cngkit
+cngkit --help
+```
 
-Help is baked into the CLI as Markdown with progressive disclosure:
+Check the installed version:
 
 ```bash
-cngkit --help
-cngkit scrub --help
-cngkit transcripts --help
-cngkit knowledges --help
-cngkit knowledges read --help
-cngkit knowledges grep --help
-cngkit knowledges glob --help
+cngkit --version
+```
+
+`cngkit` requires Node.js 20 or newer.
+
+## What It Does
+
+```bash
+cngkit login
+cngkit coderoom share
+cngkit coderoom join <room-code>
+cngkit scrub [path]
+cngkit transcripts list --limit 12
+cngkit knowledges search "cloudflare backend" --limit 3
+cngkit knowledges read /libraries/lib-cloudflare/SUBSKILL.md --limit 80
+```
+
+The CLI currently has four main jobs:
+
+- **Coderoom**: start or join a live shared working-tree room.
+- **Scrub**: scan local files for secrets and optionally mask them inline.
+- **Transcripts**: inspect local Claude and Codex transcript files from the terminal.
+- **Knowledges**: search and read the hosted Harness knowledge catalog.
+
+## Coderoom
+
+Coderoom is a live room for quickly sharing a working tree with another developer or agent.
+One machine starts a room, another joins with the room code, and the Curly backend relays
+file changes.
+
+Start a room:
+
+```bash
+cngkit coderoom share
+```
+
+Join a room:
+
+```bash
+cngkit coderoom join <room-code>
+```
+
+Use your own room code:
+
+```bash
+cngkit coderoom share design-review-01
+```
+
+Coderoom deliberately skips `.git/` and files ignored by `.gitignore`. It is a live relay,
+not durable cloud storage or a backup system. The current conflict rule is simple: the latest
+received change wins.
+
+## Harness Knowledges
+
+The `knowledges` commands read the Cloudflare-backed Harness catalog from Curly.ng. They are
+read-only and designed for AI-friendly terminal use.
+
+Check catalog health:
+
+```bash
+cngkit knowledges status
+```
+
+Find relevant knowledge:
+
+```bash
+cngkit knowledges search "cloudflare backend" --limit 3
+```
+
+Read a catalog file:
+
+```bash
+cngkit knowledges read /libraries/lib-cloudflare/SUBSKILL.md --limit 80
+```
+
+List matching files:
+
+```bash
+cngkit knowledges glob "**/*.md" --path /libraries/lib-cloudflare
+```
+
+Search inside files:
+
+```bash
+cngkit knowledges grep Cloudflare --path /libraries/lib-cloudflare --output-mode files_with_matches
 ```
 
-Global options accepted by every command:
+Return JSON for another tool:
+
+```bash
+cngkit knowledges status --json
+cngkit knowledges search "vector search" --limit 5 --json
+```
 
-- `--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.
+Catalog path shortcuts are supported. For example:
 
-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.
+```text
+/libraries/lib-cloudflare/SUBSKILL.md
+```
+
+maps to:
+
+```text
+skills/knowledges/subskills/libraries/lib-cloudflare/SUBSKILL.md
+```
 
-Command routing is implemented with Pastel route files under `src/commands/`, rendered
-through Ink. `tsup` emits a file-preserving ESM build so the published package contains
-`dist/cli.js` plus `dist/commands/**`; the private workspace client stays bundled while
-public runtime packages remain normal package dependencies.
+## Secret Scrubbing
 
-`scrub` requires the `trufflehog` binary on `PATH`. On macOS, install it with:
+`scrub` scans a file or directory with TruffleHog and prints a redacted report.
+
+```bash
+cngkit scrub .
+```
+
+Inline masking rewrites files, so it is gated behind `--yes`:
+
+```bash
+cngkit scrub . --yes
+```
+
+Masked values use this format:
+
+```text
+[CNGKIT_SECRET:<detector>:<verified|unverified>]
+```
+
+`scrub` requires the `trufflehog` binary on `PATH`.
+
+macOS install:
 
 ```bash
 brew install trufflehog
 ```
 
-Inline masking is intentionally gated behind `--yes` because it rewrites files in place.
+Safety notes:
+
+- The default mode is report-only.
+- Raw secret values are never printed.
+- `--mask` is accepted as a compatibility alias, but inline changes still require `--yes`.
 
 ## Local Agent Transcripts
 
-The `transcripts` command reads local JSONL logs from `~/.codex/sessions`,
-`~/.codex/archived_sessions`, `~/.claude/projects`, and `~/.claude/history.jsonl`.
-It is local-only operator tooling: transcript contents are not uploaded to the Curly backend.
+`transcripts` reads local JSONL files from:
+
+- `~/.codex/sessions`
+- `~/.codex/archived_sessions`
+- `~/.claude/projects`
+- `~/.claude/history.jsonl`
+
+List recent transcript files:
 
 ```bash
 cngkit transcripts list --limit 12
+```
+
+Read a transcript by path or partial session id:
+
+```bash
 cngkit transcripts read <path-or-session-id> --source codex --limit 80
+```
+
+Search recent transcript entries:
+
+```bash
 cngkit transcripts grep "deploy failed" --source all --file-limit 60 --limit 20
 ```
 
-By default, `read` and `grep` print only user/assistant text and skip internal prompt,
-hook, and tool noise. Use `--include-internal` when debugging transcript plumbing.
+Transcript commands are local-only. They do not upload transcript content to Curly.ng.
+By default, they print user and assistant text and skip internal prompt, hook, and tool noise.
+Use `--include-internal` when debugging transcript plumbing.
 
-## Coderoom
+## Backend Selection
 
-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.
+By default, `cngkit` talks to:
+
+```text
+https://curly.ng
+```
+
+Override the backend for one command:
 
 ```bash
-cngkit coderoom share
-cngkit coderoom join <room-code>
+cngkit --api-base-url https://curly.ng knowledges status
 ```
 
-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.
+Or with an environment variable:
 
-## Harness Knowledges
+```bash
+CNGKIT_API_BASE_URL=https://curly.ng cngkit knowledges status
+```
+
+## Help
 
-The `knowledges` command group reads the Cloudflare-backed Harness catalog from the
-Curly API. These commands are read-only:
+Help is baked into the CLI as Markdown:
 
 ```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
+cngkit --help
+cngkit help
+cngkit help knowledges
+cngkit coderoom --help
+cngkit knowledges read --help
+cngkit transcripts --help
 ```
 
-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>`
-(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.
+Help and machine-readable output are intentionally plain text. Status, warnings, and errors
+use Ink color in interactive terminals, but `--json`, file reads, glob results, grep results,
+and piped output stay clean.
 
-`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.
+## Terminal UI Stack
+
+`cngkit` uses the Ink family without adding a custom command framework:
+
+- **Pastel** owns command and subcommand routing through files under `src/commands/`.
+- **Ink** owns terminal rendering through built-in components such as `<Text>`.
+- **Zod** owns option and argument schemas for each route.
+
+So yes, subcommands are built in through Pastel's nested route files. Adding a
+subcommand is normally a new `.tsx` file under the matching command folder:
+
+```text
+src/commands/
+  coderoom/
+    share.tsx        cngkit coderoom share
+    join.tsx         cngkit coderoom join
+  knowledges/
+    read.tsx         cngkit knowledges read
+    grep.tsx         cngkit knowledges grep
+    glob.tsx         cngkit knowledges glob
+```
+
+The CLI does not hand-roll ANSI escape codes. Status styles go through Ink's built-in
+`<Text color="..." bold dimColor>` support. Commands that return content for agents or shell
+pipelines write raw lines instead.
+
+## For Contributors
+
+The package source lives in `apps/cng`.
+
+```text
+src/
+  cli/          Pastel bootstrap support, help text, option schemas, Ink output runner
+  commands/     Thin Pastel route files
+  features/     Command behavior grouped by feature
+  shared/       Config, output, browser, API client, shared command utilities
+```
+
+The route files under `src/commands/` should stay thin. Put behavior in
+`src/features/<feature>/`, and put cross-feature runtime helpers in `src/shared/`.
+For output, use the shared `CommandOutput` methods:
+
+- `success`, `warning`, `info`, `muted`, and `error` for human-facing terminal status.
+- `raw` for JSON, file content, file paths, grep results, and anything another tool may parse.
+
+Useful local checks:
+
+```bash
+pnpm --filter cngkit run typecheck
+pnpm --filter cngkit run lint
+pnpm --filter cngkit run build
+pnpm --filter cngkit run smoke
+```
 
-This package is mostly personal tooling for Curly.ng. It is intentionally opinionated,
-small, and practical rather than a general synchronization platform.
+The package build uses `tsup` to emit a file-preserving ESM build. The published binary is
+`dist/cli.js`, and Pastel discovers command files under `dist/commands/**`.
 
 ## License
 

package/dist/{chunk-SNTLRTQ2.js → chunk-CELXWAUR.js}

@@ -1,23 +1,15 @@
 import {
+  createCommandOutput,
   formatError
-} from "./chunk-SSRUN6G5.js";
+} from "./chunk-X3THKPHT.js";
 
-// src/ink/command-runner.tsx
+// src/cli/command-runner.tsx
 import { useEffect } from "react";
 import { useApp } from "ink";
 function CommandRunner({ run }) {
   const { exit } = useApp();
   useEffect(() => {
-    const output = {
-      info(message) {
-        process.stdout.write(`${message}
-`);
-      },
-      error(message) {
-        process.stderr.write(`${message}
-`);
-      }
-    };
+    const output = createCommandOutput(process.stdout, process.stderr);
     void run(output).catch((error) => {
       process.exitCode = 1;
       output.error(formatError(error));
@@ -31,4 +23,4 @@ function CommandRunner({ run }) {
 export {
   CommandRunner
 };
-//# sourceMappingURL=chunk-SNTLRTQ2.js.map
+//# sourceMappingURL=chunk-CELXWAUR.js.map

package/dist/chunk-CELXWAUR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/command-runner.tsx"],"sourcesContent":["import { useEffect } from \"react\";\nimport { useApp } from \"ink\";\n\nimport { createCommandOutput, formatError, type CommandOutput } from \"../shared/output.js\";\n\ntype CommandRunnerProps = {\n  readonly run: (output: CommandOutput) => Promise<void>;\n};\n\nexport function CommandRunner({ run }: CommandRunnerProps) {\n  const { exit } = useApp();\n\n  useEffect(() => {\n    const output = createCommandOutput(process.stdout, process.stderr);\n\n    void run(output)\n      .catch((error: unknown) => {\n        process.exitCode = 1;\n        output.error(formatError(error));\n      })\n      .finally(() => {\n        exit();\n      });\n  }, [exit, run]);\n\n  return null;\n}\n"],"mappings":";;;;;;AAAA,SAAS,iBAAiB;AAC1B,SAAS,cAAc;AAQhB,SAAS,cAAc,EAAE,IAAI,GAAuB;AACzD,QAAM,EAAE,KAAK,IAAI,OAAO;AAExB,YAAU,MAAM;AACd,UAAM,SAAS,oBAAoB,QAAQ,QAAQ,QAAQ,MAAM;AAEjE,SAAK,IAAI,MAAM,EACZ,MAAM,CAAC,UAAmB;AACzB,cAAQ,WAAW;AACnB,aAAO,MAAM,YAAY,KAAK,CAAC;AAAA,IACjC,CAAC,EACA,QAAQ,MAAM;AACb,WAAK;AAAA,IACP,CAAC;AAAA,EACL,GAAG,CAAC,MAAM,GAAG,CAAC;AAEd,SAAO;AACT;","names":[]}