@hulistmi/hulistmi 1.0.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 NSHipster (https://nshipster.com) — Original work (sosumi.ai)
+Copyright (c) 2026 hulistmi.ai — Derivative work
+
+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,289 @@
+# hulistmi.ai
+
+Making HarmonyOS docs AI-readable.
+
+> The `hulistmi.ai` domain is aspirational.
+> The service is currently available at
+> [`https://hulistmi-ai.y6vd2dkjgb.workers.dev`](https://hulistmi-ai.y6vd2dkjgb.workers.dev).
+
+[hulistmi-ai.y6vd2dkjgb.workers.dev](https://hulistmi-ai.y6vd2dkjgb.workers.dev)
+provides HarmonyOS developer documentation in an AI-readable format
+by converting web-rendered pages into Markdown.
+
+## Usage
+
+### HTTP API
+
+Replace `developer.huawei.com/consumer/en/doc/` with `hulistmi-ai.y6vd2dkjgb.workers.dev/`
+in any HarmonyOS documentation URL:
+
+**Original:**
+
+```
+https://developer.huawei.com/consumer/en/doc/harmonyos-guides/start-overview
+```
+
+**AI-readable:**
+
+```
+https://hulistmi-ai.y6vd2dkjgb.workers.dev/consumer/en/doc/harmonyos-guides/start-overview
+```
+
+This works for all HarmonyOS guides and API reference documentation.
+
+Search is also supported:
+
+```
+https://hulistmi-ai.y6vd2dkjgb.workers.dev/search?q=UIAbility
+```
+
+And you can browse the full documentation catalog:
+
+```
+https://hulistmi-ai.y6vd2dkjgb.workers.dev/catalog?catalogName=harmonyos-guides&language=en
+```
+
+> Only English (`en`) documentation is currently supported.
+
+### MCP Integration
+
+Hulistmi's MCP server supports Streamable HTTP transport.
+Configure your MCP client to connect to `https://hulistmi-ai.y6vd2dkjgb.workers.dev/mcp`.
+
+If your client requires stdio transport,
+you can proxy over stdio using `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "hulistmi": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://hulistmi-ai.y6vd2dkjgb.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+#### Available Tools
+
+- `searchHarmonyOSDocumentation` - Searches HarmonyOS developer documentation
+  - Parameters: `query` (string)
+  - Returns structured results with titles, URLs, and descriptions
+
+- `fetchHarmonyOSDocumentation` - Fetches a HarmonyOS documentation page as Markdown
+  - Parameters: `path` (string) — Documentation path (e.g., `/consumer/en/doc/harmonyos-guides/start-overview`)
+  - Returns content as Markdown
+
+- `fetchHarmonyOSCatalog` - Fetches a HarmonyOS documentation catalog tree
+  - Parameters: `catalogName` ("harmonyos-guides" | "harmonyos-references"), `depth` (number, optional)
+  - Returns the catalog as a Markdown listing
+
+### WebMCP
+
+Hulistmi also supports the WebMCP protocol.
+The manifest is available at:
+
+```
+https://hulistmi-ai.y6vd2dkjgb.workers.dev/webmcp/manifest.json
+```
+
+### CLI
+
+Hulistmi provides a CLI that complements MCP:
+
+```bash
+npx @hulistmi/hulistmi fetch https://developer.huawei.com/consumer/en/doc/harmonyos-guides/start-overview
+```
+
+If you use it regularly, install once:
+
+```bash
+npm i -g @hulistmi/hulistmi
+```
+
+Then use `hulistmi` directly:
+
+```bash
+hulistmi fetch https://developer.huawei.com/consumer/en/doc/harmonyos-guides/start-overview
+```
+
+Short paths work too:
+
+```bash
+hulistmi fetch /consumer/en/doc/harmonyos-guides/start-overview
+hulistmi fetch harmonyos-guides/start-overview
+```
+
+Search documentation:
+
+```bash
+hulistmi search UIAbility
+```
+
+Run a local server from the published package:
+
+```bash
+hulistmi serve
+hulistmi serve --port 8787
+```
+
+By default, output is plain text / Markdown.
+Use JSON output for scripts:
+
+```bash
+hulistmi fetch /consumer/en/doc/harmonyos-guides/start-overview --json
+hulistmi search UIAbility --json
+```
+
+### AI Agent Skill
+
+Want your AI coding assistant to use Hulistmi consistently?
+Use the hosted skill file:
+[`https://hulistmi-ai.y6vd2dkjgb.workers.dev/SKILL.md`](https://hulistmi-ai.y6vd2dkjgb.workers.dev/SKILL.md)
+
+Spec-compliant clients can also install it with:
+
+```bash
+npx skills add https://hulistmi-ai.y6vd2dkjgb.workers.dev
+```
+
+## Self-Hosting
+
+This project is designed to be easily run on your own machine
+or deployed to a hosting provider.
+
+Hulistmi.ai is currently hosted by
+[Cloudflare Workers](https://workers.cloudflare.com).
+
+> The application is built with Hono,
+> making it compatible with various runtimes.
+>
+> See the [Hono docs](https://hono.dev/docs/getting-started/basic)
+> for more information about deploying to different platforms.
+
+### Prerequisites
+
+- Node.js 20+
+- npm
+
+### Quick Start
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/hulistmi/hulistmi.ai.git
+   cd hulistmi.ai
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+3. **Start development server:**
+
+   ```bash
+   npm run dev
+   ```
+
+Once the application is up and running, press the <kbd>b</kbd>
+to open the URL in your browser.
+
+To configure MCP clients to use your development server,
+replace `hulistmi.ai` with the local server address
+(`http://localhost:8787` by default).
+
+## Development
+
+### Testing
+
+This project uses [vitest](https://vitest.dev)
+for unit and integration testing.
+
+```bash
+npm run test          # Watch mode
+npm run test:run      # Run tests once
+```
+
+> When running the CLI through npm scripts during local development,
+> use `-s` (`--silent`)
+> to suppress npm's script preamble so output pipes cleanly:
+>
+> ```bash
+> npm run -s cli -- fetch /consumer/en/doc/harmonyos-guides/start-overview | bat -l md
+> ```
+
+### Code Quality
+
+This project uses [Biome](https://biomejs.dev/)
+for code formatting, linting, and import organization.
+
+- `npm run format` - Format all code files
+- `npm run lint` - Lint and fix code issues
+- `npm run check` - Format, lint, and organize imports (recommended)
+- `npm run check:ci` - Check code without making changes (for CI)
+
+### Editor Integration
+
+For the best development experience, install the Biome extension for your editor:
+
+- [VSCode](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
+- [Vim/Neovim](https://github.com/biomejs/biome/tree/main/editors/vim)
+- [Emacs](https://github.com/biomejs/biome/tree/main/editors/emacs)
+
+### Cloudflare Workers
+
+Whenever you update your `wrangler.jsonc` or change your Worker bindings,
+be sure to re-run:
+
+```bash
+npm run cf-typegen
+```
+
+### Publishing
+
+Publishing is handled by `.github/workflows/release.yml`.
+
+- Trigger: pushed tags matching `v*` or manual dispatch with `tag`
+- Release step: `gh release create "$TAG_NAME" --generate-notes`
+- Publish auth: npm trusted publishing via OIDC (`id-token: write`)
+- Publish command: `npm publish --provenance --access public`
+
+> **Before first use:** configure npm OIDC for the `@hulistmi` scope
+> in your npm account settings under "Access Tokens" → "Publish OIDC Token".
+> Set the `registry-url` to match your npm registry.
+> Alternatively, you can publish manually with `npm publish`.
+
+## Acknowledgements
+
+hulistmi.ai is based on [sosumi.ai](https://sosumi.ai) by [NSHipster](https://nshipster.com) ([MIT](https://github.com/NSHipster/sosumi.ai/blob/main/LICENSE.md)).
+
+## License
+
+This project is available under the MIT license.
+See the [LICENSE](LICENSE.md) file for more info.
+
+## Legal
+
+This is an unofficial,
+independent project and is not affiliated with or endorsed by Huawei Technologies Co., Ltd.
+"HarmonyOS" and related marks are trademarks of Huawei Technologies Co., Ltd.
+
+This service is an accessibility-first,
+on-demand renderer.
+It converts a single HarmonyOS documentation page to Markdown only when requested by a user.
+It does not crawl, spider, or bulk download;
+it does not attempt to bypass authentication or security;
+and it implements rate limiting to avoid imposing unreasonable load.
+
+Content is fetched transiently and may be cached briefly to improve performance.
+No permanent archives are maintained.
+All copyrights and other rights in the underlying content remain with Huawei Technologies Co., Ltd.
+Each page links back to the original source.
+
+Your use of this service must comply with Huawei's Terms of Use and applicable law.
+You are solely responsible for how you access and use Huawei's content through this tool.
+Do not use this service to circumvent technical measures or for redistribution.
+
+

package/bin/hulistmi.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(scriptDir, "..");
+const cliPath = resolve(packageRoot, "src/cli.ts");
+
+const child = spawn(
+  process.execPath,
+  ["--import", "tsx/esm", cliPath, ...process.argv.slice(2)],
+  {
+    cwd: packageRoot,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  },
+);
+
+child.on("exit", (code) => process.exit(code ?? 0));

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@hulistmi/hulistmi",
+  "version": "1.0.0",
+  "description": "Making HarmonyOS docs AI-readable",
+  "license": "MIT",
+  "author": "hulistmi.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hulistmi/hulistmi.ai"
+  },
+  "keywords": [
+    "harmonyos",
+    "huawei",
+    "arkts",
+    "arkui",
+    "documentation",
+    "mcp",
+    "cli",
+    "markdown",
+    "ai"
+  ],
+  "preferGlobal": true,
+  "homepage": "https://hulistmi.ai",
+  "bugs": {
+    "url": "https://github.com/hulistmi/hulistmi.ai/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "wrangler.jsonc",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "hulistmi": "bin/hulistmi.mjs"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy --minify",
+    "cli": "node ./bin/hulistmi.mjs",
+    "cf-typegen": "wrangler types --env-interface CloudflareBindings",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "format": "biome check --write --linter-enabled=false .",
+    "lint": "biome check --formatter-enabled=false .",
+    "check": "biome check --write .",
+    "check:ci": "biome check ."
+  },
+  "dependencies": {
+    "@hono/mcp": "^0.1.2",
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "cheerio": "^1.2.0",
+    "hono": "^4.9.4",
+    "tsx": "^4.22.4",
+    "zod": "^3",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.2.2",
+    "@cloudflare/vitest-pool-workers": "^0.12.18",
+    "@vitest/ui": "^3.2.4",
+    "vitest": "^3.2.4",
+    "wrangler": "^4.32.0"
+  }
+}

package/public/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hulistmi
+description: Use when fetching or searching HarmonyOS developer documentation in AI-readable Markdown.
+---
+
+# hulistmi
+
+Use hulistmi-ai.y6vd2dkjgb.workers.dev to fetch and search HarmonyOS developer documentation in AI-readable Markdown.
+
+## HTTP API
+
+- `GET /consumer/en/doc/harmonyos-guides/<path>`
+- `GET /consumer/en/doc/harmonyos-references/<path>`
+- `GET /search?q=<query>`
+- `GET /catalog?catalogName=harmonyos-guides&language=en`
+
+## MCP Tools
+
+- `searchHarmonyOSDocumentation`
+- `fetchHarmonyOSDocumentation`
+- `fetchHarmonyOSCatalog`
+
+## CLI
+
+- `hulistmi search UIAbility --json`
+- `hulistmi fetch /consumer/en/doc/harmonyos-guides/start-overview`

package/public/_headers

@@ -0,0 +1,3 @@
+/*
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: no-referrer

package/public/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <title>hulistmi</title>
+  <rect width="64" height="64" rx="12" fill="#0f766e"/>
+  <path d="M18 42V20h6v8h16v-8h6v22h-6v-8H24v8z" fill="#ffffff"/>
+</svg>

package/public/index.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>hulistmi-ai.y6vd2dkjgb.workers.dev</title>
+    <link rel="icon" href="/favicon.svg" />
+    <style>
+      body {
+        margin: 0;
+        font-family: ui-sans-serif, system-ui, "Segoe UI", sans-serif;
+        color: #111827;
+        background: #f8fafc;
+      }
+      main {
+        max-width: 880px;
+        margin: 0 auto;
+        padding: 56px 24px;
+      }
+      h1 {
+        font-size: 42px;
+        margin: 0 0 12px;
+      }
+      p, li {
+        line-height: 1.65;
+      }
+      code {
+        background: #e5e7eb;
+        padding: 2px 5px;
+        border-radius: 4px;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>hulistmi-ai.y6vd2dkjgb.workers.dev</h1>
+      <p>AI-readable HarmonyOS documentation through HTTP, CLI, MCP, WebMCP, and agent skill discovery.</p>
+      <ul>
+        <li><code>/consumer/en/doc/harmonyos-guides/start-overview</code></li>
+        <li><code>/consumer/en/doc/harmonyos-references/js-apis-app-ability-uiability</code></li>
+        <li><code>/search?q=UIAbility</code></li>
+        <li><code>/catalog?catalogName=harmonyos-guides&amp;language=en</code></li>
+      </ul>
+      <p>hulistmi-ai.y6vd2dkjgb.workers.dev is unofficial, on-demand, transient, and not a redistribution channel.</p>
+    </main>
+  </body>
+</html>

package/public/llms.txt

@@ -0,0 +1,28 @@
+# hulistmi-ai.y6vd2dkjgb.workers.dev
+
+## HTTP API
+
+- Fetch guide Markdown: `GET /consumer/en/doc/harmonyos-guides/<path>`
+- Fetch reference Markdown: `GET /consumer/en/doc/harmonyos-references/<path>`
+- Search: `GET /search?q=<query>`
+- Catalog: `GET /catalog?catalogName=harmonyos-guides&language=en`
+
+## MCP Integration
+
+- Endpoint: `https://hulistmi-ai.y6vd2dkjgb.workers.dev/mcp`
+- WebMCP manifest: `https://hulistmi-ai.y6vd2dkjgb.workers.dev/webmcp/manifest.json`
+- Tools: `searchHarmonyOSDocumentation`, `fetchHarmonyOSDocumentation`, `fetchHarmonyOSCatalog`
+
+## CLI
+
+- Package: `@hulistmi/hulistmi`
+- Binary: `hulistmi`
+
+## AI Agent Skill
+
+- Skill: `https://hulistmi-ai.y6vd2dkjgb.workers.dev/SKILL.md`
+- Well-known skill: `https://hulistmi-ai.y6vd2dkjgb.workers.dev/.well-known/agent-skills/hulistmi/SKILL.md`
+
+## Notice
+
+hulistmi-ai.y6vd2dkjgb.workers.dev is unofficial, on-demand, transient, not an archive, not a bulk mirror, not a redistribution channel, and not a bypass mechanism for Huawei access controls.

package/public/robots.txt

@@ -0,0 +1,6 @@
+User-agent: *
+Allow: /
+Disallow: /consumer/en/doc/harmonyos-guides/
+Disallow: /consumer/en/doc/harmonyos-references/
+Disallow: /catalog
+Disallow: /search

package/public/sitemap.xml

@@ -0,0 +1,6 @@
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://hulistmi-ai.y6vd2dkjgb.workers.dev/</loc></url>
+  <url><loc>https://hulistmi-ai.y6vd2dkjgb.workers.dev/bot</loc></url>
+  <url><loc>https://hulistmi-ai.y6vd2dkjgb.workers.dev/SKILL.md</loc></url>
+  <url><loc>https://hulistmi-ai.y6vd2dkjgb.workers.dev/llms.txt</loc></url>
+</urlset>

package/public/webmcp.js

@@ -0,0 +1,3 @@
+export async function connect() {
+  return fetch("/webmcp/manifest.json").then((response) => response.json());
+}

package/src/cli.ts

@@ -0,0 +1,67 @@
+import { spawn } from "node:child_process";
+import {
+  parseCliArgs,
+  resolveFetchEndpoint,
+  resolveSearchEndpoint,
+} from "./lib/cli-endpoints";
+import { fetchHarmonyOSCatalog, renderCatalogMarkdown } from "./lib/catalog";
+import { fetchGuidePageData, renderGuideMarkdown } from "./lib/guides";
+import { fetchReferencePageData, renderReferenceMarkdown } from "./lib/reference";
+import { renderSearchMarkdown, searchHarmonyOSDocs } from "./lib/search";
+import { splitDocsPath } from "./lib/url";
+
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+  const args = parseCliArgs(argv);
+  if (args.command === "search") {
+    const result = await searchHarmonyOSDocs(args.query);
+    const output = args.json
+      ? JSON.stringify(result, null, 2)
+      : renderSearchMarkdown(result);
+    process.stdout.write(`${output}\n`);
+    return;
+  }
+  if (args.command === "fetch") {
+    const endpoint = resolveFetchEndpoint(args.input);
+    const DOC_PREFIX = "/consumer/en/doc/";
+    if (!endpoint.startsWith(DOC_PREFIX))
+      throw new Error(`Unsupported fetch endpoint: ${endpoint}`);
+    const { catalogName, pagePath } = splitDocsPath(
+      endpoint.slice(DOC_PREFIX.length),
+    );
+    const sourceUrl = `https://developer.huawei.com/consumer/en/doc/${catalogName}/${pagePath}`;
+    if (catalogName === "harmonyos-guides") {
+      const data = await fetchGuidePageData(pagePath);
+      const content = renderGuideMarkdown(data, pagePath);
+      const output = args.json
+        ? JSON.stringify({ url: sourceUrl, content }, null, 2)
+        : content;
+      process.stdout.write(`${output}\n`);
+    } else {
+      const data = await fetchReferencePageData(pagePath);
+      const content = renderReferenceMarkdown(data, pagePath);
+      const output = args.json
+        ? JSON.stringify({ url: sourceUrl, content }, null, 2)
+        : content;
+      process.stdout.write(`${output}\n`);
+    }
+    return;
+  }
+  if (args.command === "serve") {
+    const child = spawn(
+      "npm",
+      ["run", "dev", "--", "--port", String(args.port ?? 8787)],
+      { stdio: "inherit" },
+    );
+    child.on("exit", (code) => process.exit(code ?? 0));
+    return;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(
+      `hulistmi: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  });
+}