@cesarandreslopez/occ 0.8.11 → 0.9.0

package/skills/occ/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: occ
+description: >-
+  Use the occ CLI to explore unfamiliar repositories and office documents
+  efficiently for AI coding tasks. occ ("Office Cloc and Count") emits
+  token-budgeted, JSON-first output for three jobs: workspace reconnaissance
+  with "occ describe" and "occ workspace analyze"; office-document and table
+  triage for DOCX, PDF, XLSX, PPTX, ODT, ODS, and ODP with "occ doc inspect",
+  "occ sheet inspect", "occ slide inspect", and "occ table inspect"; and code
+  exploration for JS/TS, Vue SFC, and Python with "occ code map", "occ code
+  pack", "occ code find", "occ code analyze", "occ code diff", and "occ git
+  diff". Reach for it whenever you need to understand a codebase or a set of
+  office files without burning context reading everything, or whenever the user
+  mentions occ.
+metadata:
+  version: 0.9.0
+license: MIT
+---
+
+# occ — Office Cloc and Count
+
+`occ` is a **read-only** analysis CLI that helps an agent understand a repository
+or a set of office documents _cheaply_, before spending context reading files in
+full. It never modifies the target project. It shells out to a vendored `scc`
+for code metrics and to `git` for git context.
+
+Design principles to lean on:
+
+- **JSON-first** — pass `--format json` to almost any command for machine-parseable output.
+- **Token-budgeted** — `occ code map/pack` and `occ code diff` accept `--map-tokens <n>`
+  (and the root scan accepts `--token-budget <n>`). Pair with `--tokenizer o200k_base`
+  (or `cl100k_base`) for an _exact_ BPE budget instead of the default heuristic estimate.
+- **Stream large output to a file** — for big maps/packs/analyses, add `-o <file>` and
+  read it back selectively rather than flooding the conversation.
+
+## Invocation
+
+```bash
+occ <command> ...            # if installed globally (npm i -g @cesarandreslopez/occ)
+npx @cesarandreslopez/occ <command> ...   # without a global install
+```
+
+Run `occ --help` or `occ <group> --help` to see every flag.
+
+## Decision table — pick the right command
+
+| If you need to…                                         | Start with                                                                     | Deep reference                                   |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
+| Tell what kind of project a directory is                | `occ describe <dir> --format json`                                             | [reference/workspace.md](reference/workspace.md) |
+| Inventory a whole workspace (code + docs + structure)   | `occ workspace analyze <dir> --format json -o ws.json`                         | [reference/workspace.md](reference/workspace.md) |
+| Inventory / cross-reference office docs in a tree       | `occ workspace documents <dir> --format json`                                  | [reference/workspace.md](reference/workspace.md) |
+| Get document + code metrics for some directories        | `occ <dirs> --format json --structure`                                         | [reference/workspace.md](reference/workspace.md) |
+| Preflight one DOCX / PDF / ODT before reading it        | `occ doc inspect <file> --format json`                                         | [reference/documents.md](reference/documents.md) |
+| Preflight an XLSX workbook (schema, sheets, risks)      | `occ sheet inspect <file> --format json`                                       | [reference/documents.md](reference/documents.md) |
+| Preflight a PPTX / ODP deck                             | `occ slide inspect <file> --format json`                                       | [reference/documents.md](reference/documents.md) |
+| Extract structured table data from a document           | `occ table inspect <file> --format json`                                       | [reference/documents.md](reference/documents.md) |
+| Pull entities/keywords (emails, URLs, dates) from a doc | `occ doc entities <file>`                                                      | [reference/documents.md](reference/documents.md) |
+| Get oriented in an unfamiliar codebase                  | `occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md`     | [reference/code.md](reference/code.md)           |
+| Pull file _contents_ within a token budget              | `occ code pack --path . --map-tokens 8000 --tokenizer o200k_base -o pack.md`   | [reference/code.md](reference/code.md)           |
+| Find a symbol / concept (best-effort)                   | `occ code find fused "<query>" --format json`                                  | [reference/code.md](reference/code.md)           |
+| Find an exact symbol by name or type                    | `occ code find name <Name> --format json`                                      | [reference/code.md](reference/code.md)           |
+| See who calls X / what X calls                          | `occ code analyze callers <fn>` · `occ code analyze calls <fn>`                | [reference/code.md](reference/code.md)           |
+| Inspect imports / module coupling                       | `occ code analyze deps <target>` · `occ code analyze coupling <target>`        | [reference/code.md](reference/code.md)           |
+| See which _symbols_ changed in a diff                   | `occ code diff --base <ref> --map-tokens 4096 --format json`                   | [reference/code.md](reference/code.md)           |
+| List changed files / bounded patch / churn              | `occ git changed` · `occ git diff --patch --map-tokens 2048` · `occ git churn` | [reference/git.md](reference/git.md)             |
+
+## Recommended agent workflows
+
+- **Land in a new repo:** `occ describe . --format json` → `occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md`, read the map, then drill in with `occ code find` / `occ code analyze`.
+- **Review a change:** `occ git changed` → `occ code diff --base <base> --format json` for symbol-level scope → `occ git diff --patch --map-tokens 4096` for a bounded patch.
+- **Process a document drop:** `occ <dir> --format json` for the inventory → `occ doc/sheet/slide inspect --format json` per file → `occ table inspect` to pull tabular data → read only what matters.
+
+## Notes
+
+- For the full flag list of every command, read [reference/commands.md](reference/commands.md).
+- Languages with first-class code support: JavaScript, TypeScript, Vue SFC, and Python.
+- `--format json` is the integration surface; tabular output is for humans.

package/skills/occ/reference/code.md

@@ -0,0 +1,69 @@
+# Code exploration for agents
+
+`occ code` builds an in-memory code graph (no database, no daemon) for JS/TS,
+Vue SFC, and Python. Shared flags on every `code` subcommand: `--path
+<repo-root>` (default cwd), `--format json`, `-o <file>`, `--exclude-dir`,
+`--no-gitignore`, `--content-mode none|excerpt|full`, `--max-file-size-bytes
+<n>`, `--max-lines <n>`.
+
+## Orientation — `occ code map` / `occ code pack`
+
+Token-budgeted, PageRank-ranked output. `map` emits top symbol _signatures_ per
+file; `pack` emits file _content_ (optionally compressed). This is the primary
+"understand this repo cheaply" tool.
+
+```bash
+occ code map  --path . --map-tokens 8000 --tokenizer o200k_base -o map.md
+occ code pack --path . --map-tokens 8000 --tokenizer o200k_base -o pack.md
+```
+
+Shared map/pack flags: `--map-tokens <n>` (default 4096; alias `--token-budget`),
+`--tokenizer heuristic|o200k_base|cl100k_base`, `--map-format markdown|xml|json|plain`,
+`--mode map|pack`, `--compress` (pack), `--max-symbols <n>`, `--no-bias-exports`.
+
+Focus the map toward a task (boost relevant files/symbols):
+`--query "<text>"`, `--focus-path <path>` (repeatable), `--focus-depth <n>`,
+`--changed-from <ref>`, `--changed-to <ref>`, `--staged`.
+
+```bash
+occ code map --path . --query "auth token refresh" --focus-path src/auth --map-tokens 4096
+occ code map --path . --changed-from main --map-tokens 4096   # diff-focused map
+```
+
+## Search — `occ code find <mode>`
+
+- `occ code find fused "<query>"` — combines name + pattern + content search with
+  rank fusion (`--weights name:3,pattern:2,content:1`). Best when unsure.
+- `occ code find name <name>` — exact symbol name. `--file <path>` to disambiguate, `--type <node-type>`.
+- `occ code find pattern <substr>` — substring match on names.
+- `occ code find type <nodeType>` — list all nodes of a type (`file|module|function|class|interface|type-alias|enum|variable`).
+- `occ code find content <text>` — full-text search (auto-upgrades to `--content-mode full`).
+
+All accept `--limit <n>` (default 50) and `--format json`.
+
+## Relationships — `occ code analyze <kind>`
+
+- `occ code analyze calls <fn>` — what a function calls (outgoing).
+- `occ code analyze callers <fn>` — what calls a function (incoming, impact analysis).
+- `occ code analyze chain <fromFn> <toFn>` — call paths between two functions (`--depth <n>`, default 5).
+- `occ code analyze deps <target>` — module/file import relationships (local/external/unresolved).
+- `occ code analyze coupling <target>` — module-level coupling metrics.
+- `occ code analyze tree <className>` — class/interface inheritance.
+
+`calls`/`callers`/`tree` accept `--file <path>` to disambiguate. Relationships
+report `resolved` / `ambiguous` / `unresolved` status explicitly.
+
+## Change-aware — `occ code diff` / `occ code history`
+
+```bash
+occ code diff --base main --map-tokens 4096 --format json   # which symbols changed
+occ code history buildRepoMap --format json                 # git line history for a symbol
+```
+
+`code diff` flags: `--base <ref>`, `--head <ref>`, `--staged`, `--map-tokens
+<n>` (default 4096), `--tokenizer`. See also [git.md](git.md) for raw patches.
+
+## Full index — `occ code index`
+
+Build/dump the full codebase index (files, symbols, edges, capabilities). Heavy;
+prefer `map`/`find`/`analyze` for targeted questions.

package/skills/occ/reference/commands.md

@@ -0,0 +1,66 @@
+# Command cheat-sheet
+
+Every `occ` command with its canonical one-line description. Run `occ <group>
+--help` for the authoritative flag list. Most commands accept `--format
+tabular|json`, `-o <file>`, and `--ci`.
+
+## Root
+
+- `occ [directories...]` — Office Cloc and Count: scc-style summary tables for office documents. Flags: `--by-file`, `--structure`, `--quick`, `--include-ext`/`--exclude-ext`/`--exclude-dir`, `--no-gitignore`, `--sort files|name|words|size`, `--token-budget <n>`, `--tokenizer`, `--large-file-limit <mb>`, `--no-code`.
+- `occ describe [directories...]` — Quickly classify one or more directories from fast file and manifest signals.
+
+## `occ workspace` — Workspace-level analysis and document context helpers
+
+- `occ workspace describe [rootDir]` — Quickly classify a workspace from fast file and manifest signals.
+- `occ workspace analyze [rootDir]` — Analyze workspace code, documents, and structures with a versioned JSON contract. (default JSON)
+- `occ workspace documents [rootDir]` — Inspect workspace document summaries and cross-document references. (default JSON)
+
+## `occ doc` — Inspect document structure and content before deep reading
+
+- `occ doc inspect <file>` — Inspect DOCX, PDF, or ODT document metadata, structure, and content preview.
+- `occ doc entities <file>` — Extract entities (emails, URLs, dates, phone numbers, mentions) and keywords from a document.
+- `occ doc references [directories...]` — Detect cross-references between documents in directories.
+
+## `occ sheet` — Inspect spreadsheet structure and content before deep reading
+
+- `occ sheet inspect <file>` — Inspect XLSX workbook metadata, sheet inventory, schema, and token estimates.
+
+## `occ slide` — Inspect presentation structure and content before deep reading
+
+- `occ slide inspect <file>` — Inspect PPTX or ODP presentation metadata, slides, and content preview.
+
+## `occ table` — Extract and inspect table content from documents
+
+- `occ table inspect <file>` — Extract structured table data from DOCX, XLSX, PPTX, ODT, or ODP documents.
+
+## `occ code` — Explore code structure with first-class JS/TS and Python support
+
+- `occ code map` — Token-budgeted, importance-ranked repo map (top symbol signatures per file).
+- `occ code pack` — Token-budgeted, importance-ranked pack (file content, optionally compressed).
+- `occ code index` — Build the full codebase index (files, symbols, edges, capabilities).
+- `occ code find name <name>` — Find code elements by exact name.
+- `occ code find pattern <pattern>` — Find code elements by substring pattern.
+- `occ code find type <nodeType>` — List all nodes of a given type.
+- `occ code find content <text>` — Search code content (full source text).
+- `occ code find fused <query>` — Fused search combining name, pattern, and content with rank fusion.
+- `occ code analyze calls <fn>` — Show what a function calls (outgoing calls).
+- `occ code analyze callers <fn>` — Show what calls a function (incoming calls).
+- `occ code analyze chain <fromFn> <toFn>` — Find call paths between two functions.
+- `occ code analyze deps <target>` — Show module/file import relationships.
+- `occ code analyze coupling <target>` — Show module-level coupling metrics.
+- `occ code analyze tree <className>` — Show class/interface inheritance relationships.
+- `occ code diff` — Show changed symbols for a git diff range.
+- `occ code history <symbol>` — Show git line history for a symbol.
+
+## `occ git` — Inspect git changes, history, and churn
+
+- `occ git changed` — List changed files for the resolved diff range.
+- `occ git diff` — Summarize or render the resolved diff (`--patch` for a bounded raw patch).
+- `occ git history [file]` — Show commit history for a range or file.
+- `occ git churn` — Rank changed files by churn.
+
+## `occ skills` — Install and inspect the Agent Skills bundled with occ
+
+- `occ skills install [--agent claude|codex|all] [--user|--project] [--project-root <dir>] [--force] [--link]` — Install occ Agent Skills into one or more coding agents.
+- `occ skills list [--format json]` — List the Agent Skills bundled with occ.
+- `occ skills path` — Print the path to occ's bundled Agent Skills.

package/skills/occ/reference/documents.md

@@ -0,0 +1,65 @@
+# Office-document & table triage
+
+Preflight a document with `inspect` (JSON) _before_ deciding to read it in full.
+All commands accept `--format json`, `-o <file>`, and `--ci`.
+
+## `occ doc inspect <file>`
+
+Inspect DOCX, PDF, or ODT document metadata, structure, and content preview —
+metadata, risk flags, content stats, heading tree, and a short preview.
+
+```bash
+occ doc inspect report.docx --format json
+occ doc inspect report.pdf --sample-paragraphs 10
+```
+
+Flags: `--sample-paragraphs <n>` (default 5), `--no-structure` (skip heading tree).
+
+## `occ doc entities <file>`
+
+Extract entities (emails, URLs, dates, phone numbers, mentions) and keywords
+from a document. Defaults to `--format json`.
+
+## `occ doc references [directories...]`
+
+Detect cross-references between documents across directories. Defaults to JSON.
+Flags: `--exclude-dir`, `--no-gitignore`, `--ignore-pattern`.
+
+## `occ sheet inspect <file>`
+
+Inspect XLSX workbook metadata, sheet inventory, schema hints, and lightweight
+samples — including hidden sheets, named ranges, formulas, links, comments, and
+token estimates.
+
+```bash
+occ sheet inspect finance.xlsx --format json --sample-rows 3 --max-columns 12
+occ sheet inspect finance.xlsx --sheet "Q3"        # name or 1-based index
+```
+
+Flags: `--sheet <selector>`, `--sample-rows <n>` (default 5), `--header-row
+auto|none|<n>` (default auto), `--max-columns <n>` (default 50).
+
+## `occ slide inspect <file>`
+
+Inspect PPTX or ODP presentation metadata, per-slide inventory, risk flags, and
+content preview.
+
+Flags: `--sample-slides <n>` (default 3), `--slide <number>` (1-based).
+
+## `occ table inspect <file>`
+
+Extract structured table data from DOCX, XLSX, PPTX, ODT, or ODP documents —
+auto-detected headers, sample-row limits, merged-cell support.
+
+```bash
+occ table inspect report.docx --format json
+occ table inspect finance.xlsx --table 2 --sample-rows 50
+```
+
+Flags: `--table <n>` (1-based), `--sample-rows <n>` (default 20), `--header-row
+auto|none|<n>`.
+
+## Pattern
+
+`inspect --format json` → read the schema / risk flags / token estimate → only
+then read full content (or extract tables) if the document is actually relevant.

package/skills/occ/reference/git.md

@@ -0,0 +1,55 @@
+# Git context
+
+Inspect git changes, history, and churn. Shared flags: `--path <repo-root>`
+(default cwd), `--base <ref>`, `--head <ref>`, `--staged`, `--format
+tabular|json`, `-o <file>`. The diff range is resolved from `--base`/`--head`/
+`--staged` (defaults to the working-tree changes when unspecified).
+
+## `occ git changed`
+
+List changed files for the resolved diff range — a quick scope check.
+
+```bash
+occ git changed --path .
+occ git changed --base main --format json
+```
+
+## `occ git diff`
+
+Summarize the resolved diff, or render it as a bounded patch.
+
+```bash
+occ git diff --format json                              # summary (files, +/- counts)
+occ git diff --patch --map-tokens 2048 --tokenizer o200k_base   # raw patch, token-bounded
+```
+
+Flags: `--patch` (raw unified diff instead of summary), `--map-tokens <n>` +
+`--tokenizer` to cap patch size.
+
+## `occ git history [file]`
+
+Show commit history for a range or a file (hash, author date, subject).
+
+```bash
+occ git history src/cli.ts --limit 10
+occ git history --since 2025-01-01 --format json
+```
+
+Flags: `--limit <n>` (default 50), `--since <date>`, `--follow` (track renames),
+`--line-start <n>` / `--line-end <n>` (for `git log -L` line history).
+
+## `occ git churn`
+
+Rank changed files by churn — find hotspots worth attention.
+
+```bash
+occ git churn --sort churn --limit 20 --format json
+```
+
+Flags: `--sort churn|commits|added|deleted|net` (default churn), `--limit <n>`,
+`--since <date>`.
+
+## Symbol-level changes
+
+To see which _symbols_ (not just files/lines) changed, use `occ code diff`
+(see [code.md](code.md)).

package/skills/occ/reference/workspace.md

@@ -0,0 +1,65 @@
+# Workspace reconnaissance
+
+Use these to understand _what a directory is_ and inventory its contents before
+reading anything in depth. All accept `--format json` and `-o <file>`.
+
+## `occ [directories...]` — the root scan
+
+scc-style summary tables for office documents (and, by default, `scc` code metrics).
+
+```bash
+occ docs/ reports/                 # tabular metrics grouped by type
+occ . --format json                # machine-readable inventory
+occ . --structure --format json    # also extract heading trees (RAG-friendly, with char offsets)
+occ . --quick                      # file count + size by extension, skip parsing (fast)
+```
+
+Useful flags: `-f, --by-file` (row per file), `--include-ext`/`--exclude-ext`,
+`--exclude-dir <dirs>` (default `node_modules,.git`), `--no-gitignore`,
+`--sort files|name|words|size`, `--token-budget <n>` with `--tokenizer
+heuristic|o200k_base|cl100k_base`, `--large-file-limit <mb>` (default 50),
+`--no-code` (skip scc), `-o <file>`, `--ci` (ASCII only).
+
+## `occ describe [directories...]`
+
+Quickly classify one or more directories from fast file and manifest signals
+(is this a code / office / documentation / data / mixed project?).
+
+```bash
+occ describe . --format json
+occ describe apps/* --quiet        # summary only
+```
+
+Flags: `--full` (full report), `--quiet` (summary only), `--max-projects <n>`
+(default 25), `--exclude-dir`, `--no-gitignore`, `-o`.
+
+## `occ workspace describe [rootDir]`
+
+Same classification as `occ describe`, scoped to a single workspace root.
+
+## `occ workspace analyze [rootDir]`
+
+Analyze workspace code, documents, and structures with a versioned JSON contract.
+Defaults to `--format json`. This is the one-call snapshot for agents.
+
+```bash
+occ workspace analyze . -o ws.json
+occ workspace analyze . --no-documents     # code + structures only
+```
+
+Flags: `--no-code`, `--no-documents`, `--no-structures`, `--exclude-dir`,
+`--large-file-limit <mb>`, `--no-gitignore`, `-o`.
+
+## `occ workspace documents [rootDir]`
+
+Inspect workspace document summaries and cross-document references. Defaults to
+`--format json`.
+
+Flags: `--max-files <n>` (default 50), `--max-reference-files <n>` (default 20),
+`--include-markdown`, `--exclude-dir`, `-o`.
+
+## Suggested sequence
+
+1. `occ describe . --format json` — what am I looking at?
+2. `occ workspace analyze . --format json -o ws.json` — full inventory.
+3. Drill into specifics with the code or document commands.