text-compress 2.0.0 → 2.0.2

package/README.md

@@ -14,6 +14,7 @@ Brotli-compress text or entire folder trees into pasteable base64 or Z85 strings
 - **Password protection** — AES-256-GCM (`-p` / `--password`)
 - **v2 split parts** — self-describing parts; shuffled names, merged files, any sibling as entry
 - **CLI + library** — terminal or `import from "text-compress"`
+- **Agent skills** — versioned [TanStack Intent](https://tanstack.com/intent/latest/docs/overview) skills ship with the package for AI coding agents
 
 ## Install
 
@@ -21,6 +22,9 @@ Brotli-compress text or entire folder trees into pasteable base64 or Z85 strings
 npm install -g text-compress
 ```
 
+If you use an AI coding agent, run `npx @tanstack/intent@latest install` in your
+project to load versioned skills shipped with this package.
+
 Or run without installing:
 
 ```bash
@@ -168,6 +172,16 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/LEARNING.md](docs/LEA
 
 ## Changelog
 
+### v2.0.2 — `text-compress` (2026-07-09)
+
+- Ship [TanStack Intent](https://tanstack.com/intent/latest/docs/overview) agent skills (`core`, `cli`, `library`) inside the npm package
+- Add `check-skills` CI workflow and `npm run validate:skills`
+
+### v2.0.1 — `text-compress` (2026-07-08)
+
+- Republish as **`text-compress@2.0.1`** (npm name finalized after `txtc` rejection)
+- Normalized `bin` path for npm publish
+
 ### v2.0.0 — `text-compress` (2026-07-08)
 
 - New npm package **`text-compress`** (v1 remains `@startdoing/tc@1.0.4`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "text-compress",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Brotli-compress text or folders to base64/base85 strings for easy sharing",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,19 +12,22 @@
     }
   },
   "bin": {
-    "text-compress": "./dist/cli.js"
+    "text-compress": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts"
   ],
   "scripts": {
     "build": "tsc",
-    "check": "biome check --write . && tsc",
+    "check": "biome check --write . && tsc && npm run validate:skills",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "pretest": "npm run build",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "validate:skills": "intent validate"
   },
   "keywords": [
     "brotli",
@@ -33,7 +36,8 @@
     "base85",
     "z85",
     "text",
-    "archive"
+    "archive",
+    "tanstack-intent"
   ],
   "repository": {
     "type": "git",
@@ -48,11 +52,12 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.2",
-    "@types/node": "^26.1.0",
-    "tsx": "^4.19.4",
-    "typescript": "7.0.1-rc",
-    "vitest": "^4.1.9"
+    "@biomejs/biome": "^2.5.3",
+    "@tanstack/intent": "^0.3.5",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "dependencies": {
     "ignore": "^7.0.5"

package/skills/text-compress/cli/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: cli
+description: >
+  text-compress CLI: auto-detect compress vs decompress from input path or -t
+  text, -e 64/85 encoding, -p password, -s split parts, -o output, --compress
+  and --decompress force flags. No compress/decompress subcommands in v2.
+metadata:
+  type: sub-skill
+  library: text-compress
+  library_version: '2.0.2'
+sources:
+  - startdo-ing/text-compress-cli:README.md
+  - startdo-ing/text-compress-cli:src/cli/main.ts
+  - startdo-ing/text-compress-cli:src/cli/args.ts
+  - startdo-ing/text-compress-cli:src/cli/detect.ts
+---
+
+# text-compress — CLI
+
+This skill builds on text-compress/core. Read it first for encoding, pipeline,
+and v1→v2 migration context.
+
+## Setup
+
+```bash
+npm install -g text-compress
+# or without installing:
+npx text-compress ./notes.md
+```
+
+Local development:
+
+```bash
+npm run dev -- ./notes.md
+```
+
+## Core Patterns
+
+### Auto-detect compress or decompress
+
+Pass a path; the CLI picks the operation. Directories always compress. Files
+and inline text are checked for a valid compressed payload.
+
+```bash
+text-compress ./notes.md          # compress file → notes.txt
+text-compress ./notes.txt         # decompress if valid payload
+text-compress ./my-project        # compress folder
+text-compress -t "hello world"    # compress inline text
+```
+
+### Password protection
+
+```bash
+text-compress ./notes.md -p "my secret" -o locked.txt
+text-compress ./locked.txt -p "my secret" -o notes.md
+```
+
+### Base85 encoding and split output
+
+```bash
+text-compress ./notes.md -e 85
+text-compress ./large-file.txt -s 4000
+text-compress ./output.7.txt      # decompress any split sibling
+```
+
+### Force mode when auto-detect is wrong
+
+```bash
+text-compress --compress ./looks-compressed.txt
+text-compress --decompress ./plain.md
+```
+
+## Default output paths (when `-o` omitted)
+
+| Operation | Default output |
+| --- | --- |
+| Compress file/text | `<input>.txt` |
+| Compress folder | `<folder-name>.txt` |
+| Decompress text | `<input>.de.txt` |
+| Decompress folder | `<input>.de/` |
+
+## Common Mistakes
+
+### [CRITICAL] Using v1 subcommands `compress` / `decompress`
+
+Wrong:
+
+```bash
+tc compress notes.md
+tc decompress out.txt
+```
+
+Correct:
+
+```bash
+text-compress notes.md
+text-compress out.txt
+```
+
+v2 has no required subcommand. Legacy `compress`/`decompress` as the first
+argument still work but are deprecated.
+
+Source: README.md — Migration from @startdoing/tc v1
+
+### [HIGH] Omitting password on protected payload
+
+Wrong:
+
+```bash
+text-compress ./locked.txt
+```
+
+Correct:
+
+```bash
+text-compress ./locked.txt -p "my secret"
+```
+
+Password-protected payloads error without `-p`. They are **not** silently
+re-compressed.
+
+Source: src/cli/main.ts, src/payload/tags.ts
+
+### [HIGH] Passing a directory to decompress
+
+Wrong:
+
+```bash
+text-compress ./restored-project/
+```
+
+Correct:
+
+```bash
+text-compress ./restored-project.txt
+```
+
+Decompress expects a compressed file path, not an output directory.
+
+Source: src/cli/args.ts
+
+### [MEDIUM] Mixing v1 and v2 split part files
+
+Wrong:
+
+```bash
+# Expecting v1 raw concatenation without TCP\x02 headers
+text-compress ./v1-part.1.txt
+```
+
+Correct:
+
+```bash
+# v2 parts have TCP\x02 headers; pass any sibling
+text-compress ./output.7.txt
+```
+
+v2 split format is not compatible with v1.
+
+Source: README.md — v2 split output
+
+### [MEDIUM] Multiple input sources
+
+Wrong:
+
+```bash
+text-compress ./a.md -t "hello"
+```
+
+Correct:
+
+```bash
+text-compress ./a.md
+# or
+text-compress -t "hello"
+```
+
+Only one input source allowed per invocation.
+
+Source: src/cli/args.ts

package/skills/text-compress/core/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: core
+description: >
+  text-compress core concepts: Brotli-compress text or folders to pasteable
+  Base64 or Z85 strings. CLI auto-detect (compress vs decompress), library
+  API (compress, decompress, compressFolder, decompressToPath), encoding 64/85,
+  password protection, v2 split parts. Entry point for all text-compress skills.
+metadata:
+  type: core
+  library: text-compress
+  library_version: '2.0.2'
+sources:
+  - startdo-ing/text-compress-cli:README.md
+  - startdo-ing/text-compress-cli:docs/ARCHITECTURE.md
+  - startdo-ing/text-compress-cli:src/index.ts
+---
+
+# text-compress — Core Concepts
+
+`text-compress` turns UTF-8 text or entire folder trees into a single pasteable
+string (Base64 or Z85), and back again. Use the CLI for terminal workflows or
+import from `"text-compress"` in Node.js/TypeScript.
+
+**Package:** npm package `text-compress` (v2). Legacy v1 is `@startdoing/tc@1.0.4`
+— do not mix APIs or split formats between versions.
+
+## Pipeline
+
+```
+Input → type tag → Brotli (max quality) → Base64 or Z85 → pasteable string
+```
+
+Folder archives use a custom binary format before compression. Large outputs can
+be split into numbered part files for chat paste limits.
+
+## Sub-Skills
+
+| Need to... | Read |
+| --- | --- |
+| Run compress/decompress from the terminal | text-compress/cli/SKILL.md |
+| Call compress/decompress from TypeScript | text-compress/library/SKILL.md |
+
+## Quick Decision Tree
+
+- Terminal one-liner, auto-detect mode? → text-compress/cli
+- Programmatic use in Node/TS? → text-compress/library
+- Password-protected payload? → pass `-p` / `password` on both compress and decompress
+- Large output for chat paste limits? → use `-s` split (CLI) or split helpers (library)
+- Migrating from `@startdoing/tc` v1? → new package name, no subcommands, new split format
+
+## Encoding
+
+| Value | Format | When |
+| --- | --- | --- |
+| `64` (default) | Base64 | Paste anywhere |
+| `85` | Z85 (ZeroMQ RFC 32) | ~8% smaller; punctuation-safe in code blocks |
+
+Use the same encoding for compress and decompress. When `-e` is omitted on
+decompress, the CLI tries both.
+
+## Version
+
+Targets `text-compress` v2.0.2.

package/skills/text-compress/library/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: library
+description: >
+  text-compress library API: compress, decompress, compressFolder,
+  decompressToPath, decompressPayload, split helpers. Encoding 64|85, optional
+  password. TAG_TEXT vs TAG_FOLDER routing. Import from "text-compress".
+metadata:
+  type: sub-skill
+  library: text-compress
+  library_version: '2.0.2'
+sources:
+  - startdo-ing/text-compress-cli:README.md
+  - startdo-ing/text-compress-cli:src/index.ts
+  - startdo-ing/text-compress-cli:src/api/text.ts
+  - startdo-ing/text-compress-cli:src/api/folder.ts
+---
+
+# text-compress — Library API
+
+This skill builds on text-compress/core. Read it first for encoding and pipeline
+context.
+
+## Setup
+
+```ts
+import {
+  compress,
+  decompress,
+  compressFolder,
+  decompressToPath,
+} from "text-compress";
+```
+
+Requires Node.js >= 18. Package name is `"text-compress"` (not `@startdoing/tc`).
+
+## Core Patterns
+
+### Compress and decompress text
+
+```ts
+const encoded = compress("hello world");
+const restored = decompress(encoded);
+
+// Z85 encoding (~8% smaller)
+const z85 = compress("hello world", 85);
+const fromZ85 = decompress(z85, 85);
+```
+
+### Password-protected text
+
+```ts
+const locked = compress("hello world", 64, "my secret");
+const unlocked = decompress(locked, 64, "my secret");
+```
+
+### Folder archives
+
+```ts
+const { encoded, fileCount, dirCount, originalBytes } =
+  compressFolder("./my-project");
+
+decompressToPath(encoded, "./restored-project");
+```
+
+### Low-level payload access
+
+```ts
+import { decompressPayload, TAG_TEXT, TAG_FOLDER } from "text-compress";
+
+const { tag, data } = decompressPayload(encoded, 64, password);
+if (tag === TAG_TEXT) {
+  const text = data.toString("utf-8");
+}
+```
+
+## API Reference
+
+| Function | Description |
+| --- | --- |
+| `compress(text, encoding?, password?)` | UTF-8 text → encoded string (`64` or `85`) |
+| `decompress(encoded, encoding?, password?)` | Encoded text payload → string |
+| `compressFolder(dirPath, encoding?, password?)` | Folder → `{ encoded, fileCount, ... }` |
+| `decompressToPath(encoded, destDir, encoding?, password?)` | Unpack folder archive |
+| `decompressPayload(encoded, encoding?, password?)` | Low-level `{ tag, data }` |
+
+## Common Mistakes
+
+### [CRITICAL] Using v1 package import
+
+Wrong:
+
+```ts
+import { compress } from "@startdoing/tc";
+```
+
+Correct:
+
+```ts
+import { compress, decompress } from "text-compress";
+```
+
+v1 remains frozen at 1.0.4; v2 is a separate npm package.
+
+Source: README.md — Migration
+
+### [HIGH] Calling decompress on a folder payload
+
+Wrong:
+
+```ts
+const encoded = compressFolder("./project").encoded;
+const text = decompress(encoded); // throws
+```
+
+Correct:
+
+```ts
+decompressToPath(encoded, "./restored");
+```
+
+Text and folder payloads share encoding but differ by tag byte after Brotli
+decompression. `decompress()` throws if the tag is `TAG_FOLDER`.
+
+Source: src/api/text.ts
+
+### [HIGH] Calling decompressToPath on text payload
+
+Wrong:
+
+```ts
+const encoded = compress("hello");
+decompressToPath(encoded, "./out"); // throws
+```
+
+Correct:
+
+```ts
+const text = decompress(encoded);
+```
+
+Source: src/api/folder.ts
+
+### [MEDIUM] Mismatched encoding on round-trip
+
+Wrong:
+
+```ts
+const encoded = compress("hello", 85);
+const text = decompress(encoded, 64); // fails or garbage
+```
+
+Correct:
+
+```ts
+const encoded = compress("hello", 85);
+const text = decompress(encoded, 85);
+```
+
+Source: src/encoding/index.ts
+
+### [MEDIUM] compressFolder loads entire tree into memory
+
+Wrong:
+
+```ts
+// For very large folders in production scripts
+compressFolder("/huge-monorepo");
+```
+
+Correct:
+
+```bash
+# CLI uses streaming pipeline for folders (bounded memory)
+text-compress ./huge-monorepo
+```
+
+The library `compressFolder()` walks and serializes in memory. The CLI
+streaming path is internal and not exported.
+
+Source: docs/ARCHITECTURE.md — Two folder compression paths