lark-hirono 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# lark-hirono
+
+Markdown → Styled Feishu (Lark) documents with heading numbering, table conversion, and narrative optimizations.
+
+## Features
+
+- **Subcommand CLI** — `upload`, `optimize`, `fetch`, `analyze`, `highlight`, `verify`, `auth`
+- **Document types** — Automatic analysis: `catalog_table`, `data_table`, `narrative`, `mixed`
+- **Heading styling** — Blue number prefix + rainbow backgrounds per level
+- **Chinese ordinals** — `一、二、` → `1. 2.` auto-convert
+- **Table conversion** — Markdown tables → `<lark-table>` XML with proportional widths
+- **Keyword highlighting** — LLM-assisted `{red:keyword}` for table titles
+- **Narrative optimizations** — Callout injection, code block tagging, signpost bolding
+- **Chunked upload** — Large docs (>200KB) split automatically
+- **Verify** — Block-level structure validation
+
+## Install
+
+### CLI (npm)
+
+Requires Node.js 20+ and the Feishu CLI dependency used by `lark-hirono`.
+After the package is published to npm, install the latest release with:
+
+```bash
+npm install -g lark-hirono@latest
+```
+
+### Install `lark-cli`
+
+`lark-hirono` shells out to `lark-cli` for auth, document APIs, and uploads. Install it first if you do not already have it:
+
+```bash
+mkdir -p /tmp/larkcli
+cd /tmp/larkcli
+npm init -y
+npm install @larksuite/cli
+node node_modules/@larksuite/cli/scripts/install.js
+```
+
+### Claude Code Skill
+
+```bash
+npx skills add charles1614/lark-hirono
+```
+
+Then use `/lark-hirono` in Claude Code. See [`skills/lark-hirono/SKILL.md`](skills/lark-hirono/SKILL.md) for action reference.
+
+### Local Development
+
+```bash
+corepack enable
+corepack prepare pnpm@10.18.3 --activate
+pnpm install
+```
+
+### Authentication
+
+Before using the CLI or skill, authenticate with Feishu:
+
+```bash
+lark-cli auth login --domain docs
+```
+
+## Usage
+
+### Upload Local Markdown
+
+```bash
+lark-hirono upload input.md --title "My Document" --verify
+```
+
+### Optimize Existing Document
+
+Create optimized sibling (recommended):
+```bash
+lark-hirono optimize --doc GzlQwunV9iQAqmkQqOBcZzugnjf --new --verify
+```
+
+Update in-place (not recommended due to Feishu export corruption):
+```bash
+lark-hirono optimize --doc GzlQwunV9iQAqmkQqOBcZzugnjf --verify
+```
+
+### Fetch Document as Markdown
+
+```bash
+lark-hirono fetch --doc GzlQwunV9iQAqmkQqOBcZzugnjf --output out.md
+```
+
+### Analyze Document Type
+
+```bash
+lark-hirono analyze input.md
+# Output: {"document_type": "narrative", "headings": 15, "tables": "0/0"}
+```
+
+### Verify Existing Document
+
+```bash
+lark-hirono verify --doc GzlQwunV9iQAqmkQqOBcZzugnjf
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `upload <file.md>` | Create new styled Feishu document |
+| `optimize --doc <id>` | Optimize existing document |
+| `fetch --doc <id>` | Retrieve document as markdown |
+| `analyze <file.md>` | Analyze document structure |
+| `highlight <subcommand>` | Extract/apply keyword highlights |
+| `verify --doc <id>` | Validate document structure |
+| `auth <subcommand>` | Feishu authentication |
+
+### Common Flags
+
+| Flag | Description |
+|------|-------------|
+| `--doc <id>` | Feishu document ID |
+| `--new` | Create sibling doc instead of updating |
+| `--input <file>` | Local markdown source |
+| `--title <title>` | Document title |
+| `--wiki-space <id>` | Target wiki space |
+| `--wiki-node <token>` | Target parent node |
+| `--bg-mode light\|dark` | Heading background palette |
+| `--verify` | Validate after upload/optimize |
+| `--no-highlight` | Skip keyword highlighting |
+| `--dry-run` | Output to stdout, no API calls |
+| `-v, --verbose` | Detailed logging |
+
+## Pipeline
+
+```
+Upload:   Read → Normalize → Analyze → Preprocess → Split → Highlight
+          → LarkTable → Upload → Patch → Verify
+
+Optimize: Fetch → Normalize → Analyze → Narrative → Preprocess → Split
+          → LarkTable → Create → Patch → Verify
+```
+
+### Key Steps
+
+1. **Normalize** — HTML (`<p>`, `<ul>`, `<li>`, `<strong>`, `<a>`) → clean Markdown
+2. **Analyze** — Classify document type based on table count and heading density
+3. **Narrative** — For narrative docs: callout injection, code block tagging, signpost bolding
+4. **Preprocess** — Heading numbering, strip title, blue prefix + rainbow backgrounds
+5. **Split** — Oversized sections (>40KB) into chunks for API limits
+6. **Highlight** — Apply `{red:keyword}` from LLM-selected keywords (table docs only)
+7. **LarkTable** — Markdown tables → `<lark-table>` XML
+8. **Upload/Create** — Chunked doc creation via `lark-cli`
+9. **Patch** — Block-level PATCH for heading backgrounds
+10. **Verify** — Structure validation (block-level, not markdown export)
+
+## Narrative Optimizations
+
+For `documentType === "narrative"` (≥3 headings, no tables):
+
+- **Opening callout** — Inject `[!callout icon=bulb]` with first paragraph as description
+- **Code block tagging** — Detect `bash`, `nginx`, `yaml`, `python` from content patterns
+- **Blockquote conversion** — TL;DR and summary phrases → callout format
+- **Signpost bolding** — Emphasize transition phrases (`具体来说`, `值得注意的是`)
+- **Chatbot tail stripping** — Remove LLM artifact text from end of fetched docs
+
+## Config File
+
+`lark-hirono.json` in current directory or ancestors:
+
+```json
+{
+  "wikiSpace": "7620053427331681234",
+  "wikiNode": "UNtHwabqNiqc8ZkzvLscWNnwnYd",
+  "bgMode": "light",
+  "highlight": true
+}
+```
+
+Priority: CLI flags → config file → built-in defaults.
+
+## Tests
+
+```bash
+npm test  # 92 checks, all local file-based
+```
+
+## Architecture
+
+```
+src/
+├── pipeline.ts          # Master orchestration
+├── cli.ts               # Lark CLI wrapper (auth, API calls)
+├── config.ts            # Config file resolution
+├── commands/            # CLI subcommands
+│   ├── upload.ts
+│   ├── optimize.ts
+│   ├── fetch.ts
+│   ├── analyze.ts
+│   ├── highlight.ts
+│   ├── verify.ts
+│   └── auth.ts
+├── core/
+│   ├── analyze.ts       # Document classification
+│   ├── normalize.ts     # HTML→Markdown cleanup
+│   ├── preprocess.ts    # Heading numbering, strip-title
+│   ├── narrative.ts     # Narrative doc optimizations
+│   ├── headings.ts      # Chinese ordinal conversion
+│   ├── lark-table.ts    # Table → XML conversion
+│   ├── chunked.ts       # Large doc splitting
+│   └── highlight.ts     # Keyword highlighting
+├── patch/
+│   └── patch.ts         # Heading background PATCH
+├── image/
+│   └── images.ts        # Image upload
+└── verify/
+    └── verify.ts        # Structure validation
+```
+
+## Limitations
+
+### Feishu Markdown Export Corruption
+
+`lark-cli docs +fetch` does not faithfully round-trip markdown:
+- Plain text blocks exported as `##` headings
+- Consecutive paragraph lines merged (blank lines lost)
+- Code block language tags stripped (`bash` → `plaintext`)
+- Callout format simplified (blank lines removed)
+
+**Mitigation:** Verify uses block-level structure (accurate), not markdown export (corrupted).
+
+### LLM Content Emphasis Not Automated
+
+The optimization guide requires LLM judgment for:
+- `{red:关键结论}` — identifying key conclusions
+- `{green:技术术语}` — identifying technical terms
+- Insight callouts — content understanding
+
+These are **not automated** in the pipeline. Use the skill layer (`skills/lark-hirono/SKILL.md`) for LLM-assisted content optimization.
+
+## License
+
+MIT

package/dist/bin/lark-hirono.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * lark-hirono CLI — Markdown to styled Feishu documents.
+ *
+ * Usage:
+ *   lark-hirono <command> [options]
+ *
+ * Commands:
+ *   upload     Create new Feishu document from local markdown
+ *   optimize   Update existing Feishu document with pipeline transforms
+ *   fetch      Retrieve Feishu document as markdown
+ *   analyze    Analyze markdown document structure
+ *   highlight  Extract/apply keyword highlights
+ *   verify     Fetch and verify an existing document
+ *   auth       Feishu authentication (passthrough to lark-cli)
+ */
+export {};
+//# sourceMappingURL=lark-hirono.d.ts.map

package/dist/bin/lark-hirono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lark-hirono.d.ts","sourceRoot":"","sources":["../../bin/lark-hirono.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}

package/dist/bin/lark-hirono.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * lark-hirono CLI — Markdown to styled Feishu documents.
+ *
+ * Usage:
+ *   lark-hirono <command> [options]
+ *
+ * Commands:
+ *   upload     Create new Feishu document from local markdown
+ *   optimize   Update existing Feishu document with pipeline transforms
+ *   fetch      Retrieve Feishu document as markdown
+ *   analyze    Analyze markdown document structure
+ *   highlight  Extract/apply keyword highlights
+ *   verify     Fetch and verify an existing document
+ *   auth       Feishu authentication (passthrough to lark-cli)
+ */
+import * as upload from "../src/commands/upload.js";
+import * as optimize from "../src/commands/optimize.js";
+import * as fetch from "../src/commands/fetch.js";
+import * as analyze from "../src/commands/analyze.js";
+import * as highlight from "../src/commands/highlight.js";
+import * as verify from "../src/commands/verify.js";
+import * as auth from "../src/commands/auth.js";
+const COMMANDS = {
+    upload,
+    optimize,
+    fetch,
+    analyze,
+    highlight,
+    verify,
+    auth,
+};
+function showHelp() {
+    console.log(`
+lark-hirono — Markdown to styled Feishu documents
+
+Usage:
+  lark-hirono <command> [options]
+
+Commands:
+  upload <input.md>       Create new styled Feishu document from local markdown
+  optimize --doc <id>     Update existing document with pipeline transforms
+  fetch --doc <id>        Retrieve Feishu document as markdown
+  analyze <input.md>      Analyze markdown document structure
+  highlight <subcommand>  Extract/apply keyword highlights
+  verify --doc <id>       Fetch and verify an existing document
+  auth <subcommand>       Feishu authentication (passthrough to lark-cli)
+
+Options:
+  -h, --help     Show help for a command
+  -v, --verbose  Verbose logging
+
+Run "lark-hirono <command> --help" for more information.
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        showHelp();
+        process.exit(0);
+    }
+    const [cmd, ...rest] = args;
+    if (!Object.hasOwn(COMMANDS, cmd)) {
+        console.error(`Unknown command: ${cmd}`);
+        console.error("Run 'lark-hirono --help' for available commands.");
+        process.exit(1);
+    }
+    const command = COMMANDS[cmd];
+    const exitCode = await command.run(rest);
+    process.exit(exitCode);
+}
+main().catch((err) => {
+    console.error(`Fatal error: ${err.message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=lark-hirono.js.map

package/dist/bin/lark-hirono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lark-hirono.js","sourceRoot":"","sources":["../../bin/lark-hirono.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,QAAQ,MAAM,6BAA6B,CAAC;AACxD,OAAO,KAAK,KAAK,MAAM,0BAA0B,CAAC;AAClD,OAAO,KAAK,OAAO,MAAM,4BAA4B,CAAC;AACtD,OAAO,KAAK,SAAS,MAAM,8BAA8B,CAAC;AAC1D,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAC;AAEhD,MAAM,QAAQ,GAAG;IACf,MAAM;IACN,QAAQ;IACR,KAAK;IACL,OAAO;IACP,SAAS;IACT,MAAM;IACN,IAAI;CACI,CAAC;AAIX,SAAS,QAAQ;IACf,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;CAoBb,CAAC,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAClE,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAE5B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;QACzC,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAkB,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,gBAAgB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/src/cli.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Lark CLI wrapper — thin subprocess interface to `lark-cli`.
+ *
+ * Auth is handled entirely by the CLI (`lark-cli auth login`).
+ * This module only calls the CLI binary and parses JSON output.
+ */
+export declare function findLarkCli(): string;
+export interface AuthStatus {
+    appId: string;
+    brand: string;
+    identity: string;
+    tokenStatus: "valid" | "needs_refresh" | "expired";
+    userOpenId: string;
+    userName: string;
+    expiresAt: string;
+    refreshExpiresAt: string;
+    scope: string;
+}
+export interface ApiResult {
+    code: number;
+    msg: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface CliOptions {
+    cliPath?: string;
+    timeout?: number;
+    retries?: number;
+}
+export declare class LarkCli {
+    private cli;
+    private timeout;
+    private retries;
+    constructor(opts?: CliOptions);
+    /** Run lark-cli and return parsed JSON. */
+    private run;
+    /** Get current auth status. Throws if not logged in. */
+    status(): AuthStatus;
+    /** Generic GET request. */
+    get(path: string, params?: Record<string, unknown>): ApiResult | null;
+    /** Generic PATCH request. */
+    patch(path: string, data: Record<string, unknown>): ApiResult | null;
+    /** Update a section by title using replace_range mode. */
+    updateSection(docId: string, sectionTitle: string, markdown: string): boolean;
+    appendDoc(docId: string, markdown: string): boolean;
+    /** Generic POST request. */
+    post(path: string, data?: Record<string, unknown>): ApiResult | null;
+    /** Create a doc via the CLI's built-in shortcut. */
+    createDoc(title: string, markdown: string, wikiSpace?: string, wikiNode?: string): {
+        doc_id: string;
+        url: string;
+    } | null;
+    /** Get all blocks in a document. Paginates with small page_size to avoid ENOBUFS. */
+    getBlocks(docId: string): Record<string, unknown>[];
+    /** Delete a range of children from a block (batch_delete). Used for cleanup. */
+    deleteBlockChildrenTail(docId: string, parentBlockId: string, startIndex: number, endIndex: number): boolean;
+    /** Insert block children at a given index. */
+    createBlockChildren(docId: string, parentBlockId: string, children: Record<string, unknown>[], index: number): boolean;
+    /** PATCH a block with arbitrary payload. */
+    patchBlock(docId: string, blockId: string, payload: Record<string, unknown>): boolean;
+    /** Replace doc content with new markdown. */
+    updateDoc(docId: string, markdown: string): boolean;
+    /** Fetch doc content as markdown. Parses JSON stdout from lark-cli. */
+    fetchDoc(docId: string): string | null;
+}
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}