@pipeworx/mcp-tw-law 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojibake Inc.
+
+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

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# @pipeworx/tw-law
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Taiwan's national statutes and the Constitution — full text in Chinese, plus
+the Ministry of Justice's own official English translation where one exists
+— searchable by title, resolvable by exact citation, and readable one
+provision at a time.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1815+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+
+## Tools
+
+- `tw_law_search(query, limit?)` — find a law by title keyword, Chinese or
+  English ("個人資料保護法", "Personal Data Protection", "民法").
+- `tw_law_info(pcode?, name?)` — a law's full metadata: level, category,
+  official English title if any, repeal status, the last amendment date and
+  the date that amendment takes/took legal effect as SEPARATE fields, and
+  the promulgation history (Chinese, and English when translated).
+- `tw_law_toc(pcode?, name?, offset?, limit?)` — a law's chapter/section
+  structure and article numbers, paged.
+- `tw_law_article(pcode?, name?, article)` — one article's full text,
+  Chinese plus the official English translation when the Ministry has
+  published one, labelled `official`.
+
+## Auth
+
+Keyless.
+
+## Data sources
+
+- Taiwan Ministry of Justice, Laws & Regulations Database (全國法規資料庫) —
+  the Chinese text of every national statute and the Constitution, plus the
+  Ministry's own official English translations for the subset it has
+  translated (973 of 1,351 laws as of the 2026-10-15 load).
+
+The source publishes its whole catalog only as two bulk exports (Chinese,
+English), never a per-law or per-article live route — confirmed 2026-10-15.
+Per Bruce's 2026-09-23 local-copy ruling, this pack reads from a D1 copy
+loaded by `scripts/tw-law/load-data.mjs`, refreshed by re-running that
+script. `data_as_of` on every response is when that load last ran.
+
+**Licence:** 政府資料開放授權條款-第1版 (Government Open Data Licence v1), the
+licence the source's own data-reuse declaration
+(law.moj.gov.tw/Service/Copyright.aspx) names — free, non-exclusive,
+re-licensable, and explicitly permits reproduction, adaptation and public
+transmission (a mirror, not only a live proxy), conditioned on citing the
+source. Every response carries `source`.
+
+## English translations are tied to the exact Chinese version
+
+Chinese and English are two separate bulk exports from the same publisher,
+joined by this pack's loader at load time, by law title and then by article
+number (normalizing "第 6-1 條" / "Article 6-1" / "6-1" to the same key) —
+never machine-translated, never guessed. An article with no official
+translation returns `eng_content: null` and
+`has_official_english_translation: false` rather than a translation that
+doesn't exist. A law can gain or lose an official translation between loads;
+`tw_law_info`/`tw_law_search` report `has_official_english_translation` as of
+the current `data_as_of`.
+
+## Notes
+
+- `tw_law_search` is a TITLE search — it will not find a law by a phrase that
+  appears only inside an article's text.
+- Article numbering is not always contiguous: amendments can delete an
+  article or insert a sub-article ("第 1-1 條" after "第 1 條"). Use
+  `tw_law_toc` to see a law's real article numbers rather than assuming
+  1..N.
+- `effective_date` and `last_amended_date` are tracked separately because
+  Taiwanese statutes are routinely amended on one date and brought into
+  force on another (sometimes "date to be set later by the Executive Yuan"
+  — surfaced as `effective_date_pending: true`, with the full
+  `effective_note` explaining which provisions are affected).
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "tw-law": {
+      "url": "https://gateway.pipeworx.io/tw-law/mcp"
+    }
+  }
+}
+```
+
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/tw-law/mcp` returns the tools in the table
+above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
+`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
+gateway-wide set. So the tool count you see is larger than this table: a
+single-pack endpoint currently lists roughly 30 shared tools alongside the
+pack's own. The connection's `initialize` response states its exact scope, and
+is the authoritative answer for a given day.
+
+This is deliberate, not multiplexing by accident. The meta-tools are what let a
+scoped connection answer a question this pack does not cover — via
+`ask_pipeworx`, which routes across the whole catalog — without you adding a
+second MCP server. There is currently no way to mount a pack endpoint without
+them; if the extra schemas cost you more context than the routing is worth,
+connect to the full gateway once rather than to several pack endpoints.
+
+Or connect to the full Pipeworx gateway to get every pack's tools listed
+directly, instead of just this one's:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+Both URLs reach the same gateway and the same 1815+ data sources. The
+only difference is which pack's tools are listed **directly**; `ask_pipeworx`
+reaches all of them from either one.
+
+## No MCP client? Call it over HTTP
+
+```bash
+curl -X POST https://gateway.pipeworx.io/v1/tools/tw_law_search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"個人資料保護法"}'
+```
+
+No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/tw_law_search`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+
+## Standalone (no gateway account)
+
+This package also runs as a local stdio MCP server — no Pipeworx account, no
+gateway round-trip:
+
+```json
+{
+  "mcpServers": {
+    "tw-law": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-tw-law"]
+    }
+  }
+}
+```
+
+Or run it directly to confirm it starts:
+
+```bash
+npx -y @pipeworx/mcp-tw-law
+```
+
+It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
+for **only** this pack's tools — none of the shared meta-tools the gateway
+connection above adds. Same source, same tools, no ask_pipeworx routing.
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English —
+this works on the pack endpoint above as well as on the full gateway:
+
+```
+ask_pipeworx({ question: "your question about Tw Law data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [Docs and guides](https://pipeworx.io/docs)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+//
+// Entry point for `npx @pipeworx/mcp-<slug>`.
+//
+// Packs ship as raw TypeScript (no build step — see publish-pack.sh for why:
+// tsx sidesteps every extensionless-import / bare-JSON-import edge case a
+// per-pack tsc build would have to solve one pack at a time). This file
+// registers tsx's ESM loader programmatically, then hands off to src/server.ts,
+// which wraps the pack's {tools, callTool} export in a stdio MCP server.
+//
+// Copied verbatim into every published pack repo by scripts/publish-pack.sh —
+// edit this file, not a per-pack copy.
+import { register } from 'tsx/esm/api';
+
+register();
+
+await import('../src/server.ts');

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@pipeworx/mcp-tw-law",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "tw-law — Taiwan national statutes and the Constitution, in Chinese plus the Ministry of Justice's own official English translations where one exists, from the Ministry of Justice Laws & Regulations Database (全國法規資料庫). Fleet #3129.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "mcp-tw-law": "bin/cli.js"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "tw-law"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-tw-law.git"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@cloudflare/workers-types": "^4.20260405.1"
+  },
+  "pipeworx": {
+    "sourceHash": "v1-93f7e951839b7103df727620fff2c2dd9349d7ec823117325ece1c28e2bfcafd",
+    "sourceCommit": "fe38188882d0fe91e5a45d82b7b989b4aae1e8b6"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/tw-law",
+  "title": "Tw Law",
+  "description": "tw-law — Taiwan national statutes and the Constitution, in Chinese plus the Ministry of Justice's…",
+  "version": "0.1.0",
+  "websiteUrl": "https://pipeworx.io/packs/tw-law",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-tw-law",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/tw-law/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,223 @@
+interface McpToolDefinition {
+  name: string;
+  description: string;
+  /** Human-facing one-liner (fleet #1967). Optional; consumers fall back to
+   *  description. Kept in step with shared/src/types.ts — scripts/lib/
+   *  check-inlined-types.mjs reports drift at publish time. */
+  summary?: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    anyOf?: Array<{ required: string[] }>;
+    oneOf?: Array<{ required: string[] }>;
+    allOf?: Array<{ required: string[] }>;
+  };
+  outputSchema?: Record<string, unknown>;
+}
+
+interface McpToolExport {
+  tools: McpToolDefinition[];
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
+}
+
+/**
+ * tw-law — Taiwan national statutes and the Constitution, in Chinese plus
+ * the Ministry of Justice's own official English translations where one
+ * exists, from the Ministry of Justice Laws & Regulations Database
+ * (全國法規資料庫). Fleet #3129.
+ *
+ * The source publishes its whole catalog only as two bulk JSON exports (no
+ * per-law or per-article live route — verified 2026-10-15), so this pack
+ * reads from a D1 copy loaded and refreshed by scripts/tw-law/load-data.mjs,
+ * per Bruce's 2026-09-23 local-copy ruling. See src/store.ts for the licence
+ * and the full load path.
+ *
+ * Every response carries `source` and `data_as_of` (when the load last ran).
+ * Every English field is the Ministry's OWN translation, tied to the exact
+ * Chinese law/article it translates, and labelled official — never a
+ * machine translation.
+ */
+import {
+  type D1Like,
+  dataAsOf,
+  getArticle,
+  getHeadingBefore,
+  getLaw,
+  getToc,
+  requireDb,
+  searchLaws,
+  shapeLaw,
+  SOURCE,
+} from './store.js';
+
+const tools: McpToolExport['tools'] = [
+  {
+    name: 'tw_law_search',
+    description:
+      'Search Taiwan national statutes and the Constitution by TITLE keyword, Chinese or English — "個人資料保護法", "Personal Data Protection", "民法", "Civil Code". This is a title search, not full-text; it will not find a law by a phrase appearing only inside an article. Returns each match\'s pcode (for tw_law_info/tw_law_article), Chinese and English titles, law level, category, whether an official English translation exists, and the last amendment date. Source: Taiwan Ministry of Justice, Laws & Regulations Database.',
+    summary: 'Find a Taiwan law by title (Chinese or English).',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        query: { type: 'string', description: 'Title keyword, Chinese or English, e.g. "個人資料保護法" or "Personal Data Protection Act".' },
+        limit: { type: 'number', description: 'Max laws to return (1-50, default 10).' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'tw_law_info',
+    description:
+      'Resolve a Taiwan law to its full metadata by pcode (from tw_law_search) or an exact/partial Chinese or English title — the exact-citation step before reading an article. Returns the law\'s level (法律/憲法), category, official English title if one exists, whether it has been abolished, the LAST AMENDMENT date and the date that amendment TAKES/TOOK LEGAL EFFECT as separate fields (Taiwan statutes can be amended on one date and take effect on another, sometimes "to be set later by the Executive Yuan" — flagged as effective_date_pending), the full promulgation history (in Chinese, and in English when the law has an official translation), and the article count. Source: Taiwan Ministry of Justice, Laws & Regulations Database.',
+    summary: "One Taiwan law's metadata: level, category, amendment vs. effective dates, repeal status, promulgation history.",
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        pcode: { type: 'string', description: 'The law\'s pcode, e.g. "I0050021" (from tw_law_search).' },
+        name: { type: 'string', description: 'Chinese or English law title, exact or partial, used when pcode is not known.' },
+      },
+    },
+  },
+  {
+    name: 'tw_law_toc',
+    description:
+      'Table of contents for one Taiwan law: its chapter/section headings and the article number of every provision, in order, paged. Use to browse a law\'s structure before reading a specific article with tw_law_article, or to enumerate every article number a long law has. Returns has_more and next_offset when the law has more entries than the page size.',
+    summary: "A Taiwan law's chapter structure and article numbers, paged.",
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        pcode: { type: 'string', description: 'The law\'s pcode (from tw_law_search or tw_law_info).' },
+        name: { type: 'string', description: 'Chinese or English law title, used when pcode is not known.' },
+        offset: { type: 'number', description: 'Pagination offset (default 0).' },
+        limit: { type: 'number', description: 'Max entries to return (1-500, default 200).' },
+      },
+    },
+  },
+  {
+    name: 'tw_law_article',
+    description:
+      'Full text of ONE article (條) of a Taiwan law, by pcode or title plus article number in any spelling — "2", "第 2 條", "Article 2", "第 6-1 條", "Article 6-1". Returns the Chinese text and, when the Ministry has published an official English translation of that law, the official English text of the SAME article, labelled official (never a machine translation) — plus the chapter/section heading it falls under. A long law is never returned whole; use tw_law_toc to find article numbers, and call this once per article.',
+    summary: 'One article of a Taiwan law, Chinese plus the official English translation when one exists.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        pcode: { type: 'string', description: 'The law\'s pcode (from tw_law_search or tw_law_info).' },
+        name: { type: 'string', description: 'Chinese or English law title, used when pcode is not known.' },
+        article: { type: 'string', description: 'Article number, any spelling: "2", "第 2 條", "Article 2", "6-1".' },
+      },
+      required: ['article'],
+    },
+  },
+];
+
+function clamp(v: unknown, lo: number, hi: number, d: number): number {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) && n > 0 ? Math.min(hi, Math.max(lo, n)) : d;
+}
+
+async function resolvePcode(db: D1Like, args: Record<string, unknown>): Promise<string> {
+  const pcode = args.pcode != null ? String(args.pcode).trim() : '';
+  const name = args.name != null ? String(args.name).trim() : '';
+  if (!pcode && !name) throw new Error('Provide either "pcode" (from tw_law_search) or "name" (a Chinese or English law title).');
+  const law = await getLaw(db, { pcode: pcode || undefined, name: name || undefined });
+  if (!law) throw new Error(`No Taiwan law found for ${pcode ? `pcode "${pcode}"` : `name "${name}"`}. Try tw_law_search first.`);
+  return law.pcode;
+}
+
+async function searchTool(db: D1Like, args: Record<string, unknown>) {
+  const query = String(args.query ?? '').trim();
+  if (!query) throw new Error('Required argument "query" is missing (a Chinese or English law title keyword).');
+  const limit = clamp(args.limit, 1, 50, 10);
+  const rows = await searchLaws(db, { query, limit });
+  return {
+    query,
+    returned: rows.length,
+    laws: rows.map((r) => ({ ...shapeLaw(r), matched_on: r.matched_on })),
+    note: rows.length === 0 ? 'No law title matched. This is a title search — try tw_law_search with a different keyword, not an article phrase.' : undefined,
+    source: SOURCE,
+    data_as_of: await dataAsOf(db),
+  };
+}
+
+async function infoTool(db: D1Like, args: Record<string, unknown>) {
+  const pcode = args.pcode != null ? String(args.pcode).trim() : '';
+  const name = args.name != null ? String(args.name).trim() : '';
+  if (!pcode && !name) throw new Error('Provide either "pcode" (from tw_law_search) or "name" (a Chinese or English law title).');
+  const law = await getLaw(db, { pcode: pcode || undefined, name: name || undefined });
+  if (!law) throw new Error(`No Taiwan law found for ${pcode ? `pcode "${pcode}"` : `name "${name}"`}. Try tw_law_search first.`);
+  return { ...shapeLaw(law), data_as_of: await dataAsOf(db) };
+}
+
+async function tocTool(db: D1Like, args: Record<string, unknown>) {
+  const pcode = await resolvePcode(db, args);
+  const offset = clamp(args.offset, 0, 1_000_000, 0);
+  const limit = clamp(args.limit, 1, 500, 200);
+  const { rows, total } = await getToc(db, { pcode, offset, limit });
+  return {
+    pcode,
+    total_entries: total,
+    returned: rows.length,
+    offset,
+    entries: rows.map((r) => ({
+      seq: r.seq,
+      kind: r.article_type === 'C' ? 'heading' : 'article',
+      article_no: r.article_no || null,
+      eng_article_no: r.eng_article_no || null,
+      text: r.article_type === 'C' ? r.content : undefined,
+    })),
+    has_more: offset + rows.length < total,
+    next_offset: offset + rows.length < total ? offset + rows.length : null,
+    source: SOURCE,
+    data_as_of: await dataAsOf(db),
+  };
+}
+
+async function articleTool(db: D1Like, args: Record<string, unknown>) {
+  const articleArg = args.article != null ? String(args.article).trim() : '';
+  if (!articleArg) throw new Error('Required argument "article" is missing, e.g. "2" or "Article 2".');
+  const pcode = await resolvePcode(db, args);
+  const row = await getArticle(db, { pcode, articleNo: articleArg });
+  if (!row) {
+    throw new Error(
+      `No article "${articleArg}" found for this law. Use tw_law_toc to list its real article numbers — some laws skip numbers or use "-1"/"-2" sub-articles.`,
+    );
+  }
+  const law = await getLaw(db, { pcode });
+  const heading = await getHeadingBefore(db, { pcode, seq: row.seq });
+  return {
+    pcode,
+    law_name: law?.law_name ?? null,
+    eng_law_name: law?.eng_law_name ?? null,
+    heading: heading,
+    article_no: row.article_no,
+    content: row.content,
+    eng_article_no: row.eng_article_no,
+    eng_content: row.eng_content,
+    translation_label: row.eng_content ? 'official' : null,
+    has_official_english_translation: !!row.eng_content,
+    source: SOURCE,
+    data_as_of: await dataAsOf(db),
+  };
+}
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  const db = requireDb(args._d1);
+  switch (name) {
+    case 'tw_law_search':
+      return searchTool(db, args);
+    case 'tw_law_info':
+      return infoTool(db, args);
+    case 'tw_law_toc':
+      return tocTool(db, args);
+    case 'tw_law_article':
+      return articleTool(db, args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export default { tools, callTool, meter: { credits: 1 } } satisfies McpToolExport;

package/src/server.ts

@@ -0,0 +1,48 @@
+/**
+ * Stdio MCP server entry point for @pipeworx/mcp-tw-law.
+ * Generated by scripts/publish-pack.sh — do not hand-edit in the pack repo;
+ * edit scripts/publish-pack.sh (the server.ts heredoc) and republish instead.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import pack from './index.js';
+
+
+const server = new Server(
+  { name: '@pipeworx/mcp-tw-law', version: '0.1.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: pack.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const callArgs = { ...((args ?? {}) as Record<string, unknown>) };
+    
+    const result = await pack.callTool(name, callArgs);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Fatal error running server:', err);
+  process.exit(1);
+});

package/src/store.ts

@@ -0,0 +1,214 @@
+/**
+ * Reads for tw-law (fleet #3129).
+ *
+ * Taiwan's Ministry of Justice Laws & Regulations Database
+ * (全國法規資料庫, law.moj.gov.tw) publishes its whole catalog — every national
+ * statute and the Constitution, in Chinese, plus the Ministry's own official
+ * English translations where one exists — only as two bulk JSON exports (one
+ * per language), never a per-law or per-article live route (verified
+ * 2026-10-15: both `/api/Ch/Law/JSON` and `/api/En/Law/JSON` return a zip of
+ * the ENTIRE catalog; there is no `LawSearchContent`-style per-item endpoint).
+ * Per Bruce's 2026-09-23 ruling on bulk-only sources, `scripts/tw-law/load-data.mjs`
+ * downloads both exports, joins each Chinese law to its official English
+ * translation by title (the join key the source itself uses — see that
+ * script's header), and writes the result into a D1 database the gateway
+ * hands this pack as `_d1`
+ * (pack-manifest "d1Binding": "TW_LAW_DB"). Table/column names here must
+ * match that script's buildSchemaSql().
+ *
+ * Licence: 政府資料開放授權條款-第1版 (Government Open Data Licence v1), the
+ * licence law.moj.gov.tw's own data-reuse declaration
+ * (law.moj.gov.tw/Service/Copyright.aspx) names for this database — free,
+ * non-exclusive, re-licensable, and explicitly permits reproduction,
+ * adaptation and public transmission (i.e. a mirror, not just a live proxy),
+ * conditioned only on citing the source. That is what is cited below.
+ */
+
+/** The slice of Cloudflare's D1Database this pack uses, declared here so the
+ *  pack needs no workers-types and a test can pass a node:sqlite stub. */
+export interface D1Like {
+  prepare(sql: string): D1StmtLike;
+}
+export interface D1StmtLike {
+  bind(...values: unknown[]): D1StmtLike;
+  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+}
+
+// Provenance is publisher + dataset + data_as_of (CLAUDE.md step 9b) — never
+// the download route.
+export const SOURCE = 'Taiwan Ministry of Justice, Laws & Regulations Database (全國法規資料庫)';
+export const LICENSE =
+  '政府資料開放授權條款-第1版 (Government Open Data Licence v1) — free, non-exclusive, ' +
+  're-licensable reuse including reproduction and public transmission, conditioned on citing the source.';
+
+export class StoreUnavailableError extends Error {
+  constructor() {
+    super(
+      'tw-law: the law store is not bound in this runtime (no _d1). These tools only answer through the Pipeworx gateway; a standalone install has no data to read.',
+    );
+    this.name = 'StoreUnavailableError';
+  }
+}
+export function requireDb(d1: unknown): D1Like {
+  if (!d1 || typeof (d1 as D1Like).prepare !== 'function') throw new StoreUnavailableError();
+  return d1 as D1Like;
+}
+
+export interface LawRow {
+  pcode: string;
+  law_name: string;
+  eng_law_name: string | null;
+  law_level: string;
+  law_category: string | null;
+  law_url: string;
+  eng_law_url: string | null;
+  has_eng_version: number;
+  modified_date: string | null;
+  effective_date: string | null;
+  effective_note: string | null;
+  abandon_note: string | null;
+  foreword: string | null;
+  histories: string | null;
+  eng_histories: string | null;
+  article_count: number;
+}
+
+const LAW_COLS = `pcode, law_name, eng_law_name, law_level, law_category, law_url, eng_law_url, has_eng_version,
+  modified_date, effective_date, effective_note, abandon_note, foreword, histories, eng_histories, article_count`;
+
+/** Chinese government dates are plain YYYYMMDD strings; a few historical
+ *  entries are empty (effective on promulgation) or the "99991231" sentinel
+ *  the source itself uses for "date set later by the Executive Yuan" — never
+ *  guess a real date for either, surface them as given. */
+function fmtDate(raw: string | null): string | null {
+  if (!raw) return null;
+  if (raw === '99991231') return null;
+  const m = /^(\d{4})(\d{2})(\d{2})$/.exec(raw);
+  return m ? `${m[1]}-${m[2]}-${m[3]}` : raw;
+}
+
+function isPending(raw: string | null): boolean {
+  return raw === '99991231';
+}
+
+export function shapeLaw(r: LawRow) {
+  return {
+    pcode: r.pcode,
+    law_name: r.law_name,
+    eng_law_name: r.eng_law_name,
+    law_level: r.law_level,
+    law_category: r.law_category,
+    law_url: r.law_url,
+    eng_law_url: r.eng_law_url,
+    has_official_english_translation: r.has_eng_version === 1,
+    abolished: !!(r.abandon_note && r.abandon_note.trim()),
+    abandon_note: r.abandon_note || null,
+    // Dates kept apart per the legal-pack contract: amendment date (most
+    // recent change to the text) vs. the date that amendment takes/took
+    // legal effect — the source tracks these as two separate fields, and so
+    // does this pack.
+    last_amended_date: fmtDate(r.modified_date),
+    effective_date: fmtDate(r.effective_date),
+    effective_date_pending: isPending(r.effective_date),
+    effective_note: r.effective_note || null,
+    foreword: r.foreword || null,
+    promulgation_history: r.histories || null,
+    promulgation_history_english: r.eng_histories || null,
+    article_count: r.article_count,
+    source: SOURCE,
+  };
+}
+
+export async function dataAsOf(db: D1Like): Promise<string | null> {
+  const r = await db.prepare(`SELECT value FROM tw_law_meta WHERE key = 'loaded_at'`).first<{ value: string }>();
+  return r?.value ?? null;
+}
+
+/** The whole catalog is 1,351 laws — a LIKE scan over that is trivial, so
+ *  title search skips FTS5 entirely (and the chunked-import trap that comes
+ *  with it; see reference_d1_fts5_import_trap) in favor of a plain
+ *  substring match on both the Chinese and English titles. */
+export async function searchLaws(
+  db: D1Like,
+  opts: { query: string; limit: number },
+): Promise<Array<LawRow & { matched_on: 'chinese_title' | 'english_title' }>> {
+  const q = opts.query.trim();
+  if (!q) return [];
+  const cols = LAW_COLS.split(',').map((c) => `l.${c.trim()}`).join(', ');
+  const r = await db
+    .prepare(
+      `SELECT ${cols},
+         CASE WHEN l.law_name LIKE ? THEN 'chinese_title' ELSE 'english_title' END AS matched_on
+       FROM tw_laws l WHERE l.law_name LIKE ? OR l.eng_law_name LIKE ?
+       ORDER BY length(l.law_name) LIMIT ?`,
+    )
+    .bind(`%${q}%`, `%${q}%`, `%${q}%`, opts.limit)
+    .all<LawRow & { matched_on: 'chinese_title' | 'english_title' }>();
+  return r.results;
+}
+
+export async function getLaw(db: D1Like, opts: { pcode?: string; name?: string }): Promise<LawRow | null> {
+  if (opts.pcode) {
+    return db.prepare(`SELECT ${LAW_COLS} FROM tw_laws WHERE pcode = ?`).bind(opts.pcode).first<LawRow>();
+  }
+  if (opts.name) {
+    const exact = await db.prepare(`SELECT ${LAW_COLS} FROM tw_laws WHERE law_name = ? OR eng_law_name = ?`).bind(opts.name, opts.name).first<LawRow>();
+    if (exact) return exact;
+    return db
+      .prepare(`SELECT ${LAW_COLS} FROM tw_laws WHERE law_name LIKE ? OR eng_law_name LIKE ? ORDER BY length(law_name) LIMIT 1`)
+      .bind(`%${opts.name}%`, `%${opts.name}%`)
+      .first<LawRow>();
+  }
+  return null;
+}
+
+export interface ArticleRow {
+  seq: number;
+  article_type: 'A' | 'C';
+  article_no: string | null;
+  article_no_norm: string | null;
+  content: string;
+  eng_article_no: string | null;
+  eng_content: string | null;
+}
+const ARTICLE_COLS = 'seq, article_type, article_no, article_no_norm, content, eng_article_no, eng_content';
+
+export async function getToc(
+  db: D1Like,
+  opts: { pcode: string; offset: number; limit: number },
+): Promise<{ rows: ArticleRow[]; total: number }> {
+  const total = await db.prepare(`SELECT count(*) AS n FROM tw_articles WHERE pcode = ?`).bind(opts.pcode).first<{ n: number }>();
+  const r = await db
+    .prepare(`SELECT ${ARTICLE_COLS} FROM tw_articles WHERE pcode = ? ORDER BY seq LIMIT ? OFFSET ?`)
+    .bind(opts.pcode, opts.limit, opts.offset)
+    .all<ArticleRow>();
+  return { rows: r.results, total: total?.n ?? 0 };
+}
+
+/** "第 2 條" / "2" / "Article 2" / "第 6-1 條" / "Article 6-1" all normalize
+ *  to the same key the loader stored, so any of the source's own spellings
+ *  (Chinese or English) resolves a provision. */
+export function normalizeArticleNo(v: string): string {
+  const m = /(\d+)(?:[-之](\d+))?/.exec(String(v));
+  if (!m) return String(v).trim();
+  return m[2] ? `${m[1]}-${m[2]}` : m[1];
+}
+
+export async function getArticle(db: D1Like, opts: { pcode: string; articleNo: string }): Promise<ArticleRow | null> {
+  const norm = normalizeArticleNo(opts.articleNo);
+  return db
+    .prepare(`SELECT ${ARTICLE_COLS} FROM tw_articles WHERE pcode = ? AND article_type = 'A' AND article_no_norm = ? LIMIT 1`)
+    .bind(opts.pcode, norm)
+    .first<ArticleRow>();
+}
+
+/** The chapter/section heading (ArticleType 'C') immediately preceding a
+ *  given seq, for context — "第 一 章 總則" above Article 1, etc. */
+export async function getHeadingBefore(db: D1Like, opts: { pcode: string; seq: number }): Promise<string | null> {
+  const r = await db
+    .prepare(`SELECT content FROM tw_articles WHERE pcode = ? AND article_type = 'C' AND seq < ? ORDER BY seq DESC LIMIT 1`)
+    .bind(opts.pcode, opts.seq)
+    .first<{ content: string }>();
+  return r?.content ?? null;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["src/server.ts"]
+}