@plurnk/plurnk-mimetypes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories
+
+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,124 @@
+# @plurnk/plurnk-mimetypes
+
+Framework + detection service for the `@plurnk/plurnk-mimetypes-*` handler family. Sits between [plurnk-service](https://github.com/plurnk/plurnk-service) (the engine) and individual per-mimetype handler repos (the implementations).
+
+plurnk-service hands a path or content blob to `Mimetypes.process(...)` and gets back `{ mimetype, symbols, preview, ok }`. The service stays mimetype-illiterate; this helper owns detection, discovery, handler instantiation, outline formatting, token-budgeted preview truncation, the duck contract spec, and the build utilities handler repos consume.
+
+## install
+
+```
+npm install @plurnk/plurnk-mimetypes
+```
+
+Requires Node ≥ 25 (native TypeScript support, ESM only).
+
+## use — orchestrator (plurnk-service side)
+
+```ts
+import { Mimetypes } from "@plurnk/plurnk-mimetypes";
+
+const mimetypes = new Mimetypes({
+    tokenize: async (text) => myProviderTokenizer(text),
+});
+
+const result = await mimetypes.process(
+    { path: "src/main.py" },
+    { budget: 256 },
+);
+// result.mimetype === "text/x-python"
+// result.symbols  === structural outline (string)
+// result.preview  === bounded outline within budget tokens
+// result.ok       === true
+```
+
+Without a budget the preview is unbounded — equivalent to `symbols`. plurnk-service supplies the real budget (sourced from `PLURNK_ENTRY_SIZE_DEFAULT_TOKENS`).
+
+Pipeline failure modes are documented in [SPEC.md](SPEC.md#error-policy).
+
+## use — handler authors
+
+A handler is a class extending `BaseHandler` (or `AntlrExtractor` for grammar-backed extraction). The framework derives `symbols`, `preview`, and `validate` from your single `extract(content)` method.
+
+```ts
+import { BaseHandler } from "@plurnk/plurnk-mimetypes";
+import type { MimeSymbol } from "@plurnk/plurnk-mimetypes";
+
+export default class TextSomething extends BaseHandler {
+    extract(content: string): MimeSymbol[] {
+        // return structural declarations as MimeSymbol[]
+        return [];
+    }
+}
+```
+
+Discovery: declare yourself in `package.json`.
+
+```json
+{
+    "plurnk": {
+        "kind": "mimetype",
+        "name": "text/something",
+        "glyph": "✨",
+        "extensions": [".sth"]
+    }
+}
+```
+
+Reference handler: [plurnk/plurnk-mimetypes-text-markdown](https://github.com/plurnk/plurnk-mimetypes-text-markdown). Fork and adapt for new mimetypes — it's a real production handler, not a synthetic skeleton.
+
+For grammar-backed handlers, vendor your `.g4` files in `grammar/`, run `npx plurnk-mimetypes-compile`, and switch the parent class to `AntlrExtractor`. ANTLR handlers add the runtime and compiler to their own devDependencies (the framework declares both as optional peer deps so consumers who only use `BaseHandler`/`Mimetypes` don't pay):
+
+```
+npm install --save-dev antlr-ng@^1.0.10 antlr4ng@^3.0.0
+```
+
+See [SPEC.md](SPEC.md#9-antlr-extractor) for the full handler wiring.
+
+## public API
+
+The package exposes its full primitive surface for tools building on top of it:
+
+| Export | Purpose |
+|---|---|
+| `Mimetypes` | top-level pipeline orchestrator (`process`, `detect`, `getHandler`, `ready`) |
+| `BaseHandler` | base class for handlers (default export) |
+| `AntlrExtractor` | base class for ANTLR-backed handlers |
+| `withExtractor(BaseVisitor)` | mixin that adds symbol-collection state to any antlr4ng visitor |
+| `detect(input, registry)` | path/ext/hint/content → mimetype resolver |
+| `discover(options)` | scan installed `@plurnk/plurnk-mimetypes-*` packages |
+| `emptyRegistry()` | construct an empty `Registry` |
+| `format(symbols)` | `MimeSymbol[]` → indented outline string |
+| `fit(symbols, budget, tokenize)` | drop-deepest-first token-budget truncation |
+| `fitContent(content, budget, tokenize)` | raw-content token-budget truncation |
+| `buildTree(symbols)` | flat `MimeSymbol[]` → nested `TreeNode[]` |
+| `renderTree(nodes)` | `TreeNode[]` → outline string |
+| `maxDepth(nodes)` | tree's maximum nesting depth |
+| `pruneToMaxDepth(nodes, limit)` | drop nodes deeper than `limit` |
+| `runCompile(opts)` | invoke antlr-ng + post-process imports |
+| `rewriteImports(dir)` | rewrite `.js` import extensions to `.ts` |
+| `defaultTokenize` | fallback heuristic (`text.length / 2`); biased toward safety |
+
+Public types: `MimeSymbol`, `SymbolKind`, `HandlerMetadata`, `HandlerOptions`, `TokenizeFn`, `ExtractionVisitor`, `Registry`, `DetectInput`, `HandlerInfo`, `Discovery`, `DiscoverOptions`, `TreeNode`, `CompileOptions`, `HandlerLoader`, `MimetypesOptions`, `ProcessInput`, `ProcessOptions`, `ProcessResult`.
+
+## cli
+
+```
+plurnk-mimetypes-compile      compile grammar/ → src/generated/ via antlr-ng
+                              and rewrite .js import extensions to .ts
+```
+
+Run from a handler repo's root directory.
+
+## development
+
+```
+npm install
+npm run build
+npm test
+```
+
+`test:lint`, `test:unit`, `test:intg` separately if needed. No biome / eslint — `tsc --noEmit` is lint.
+
+## license
+
+MIT.

package/SPEC.md

@@ -0,0 +1,187 @@
+# @plurnk/plurnk-mimetypes — Specification
+
+This document defines the duck contract, pipeline, data shapes, and policies that the framework owns. Per-mimetype handler repos consume this spec; plurnk-service consumes the pipeline.
+
+The eventual home for the formal version of this contract is JSON Schema in [`@plurnk/plurnk-grammar`](https://github.com/plurnk/plurnk-grammar). Until then, this plain-text spec is authoritative.
+
+---
+
+## 1. Duck contract
+
+A handler is any class instance whose shape matches:
+
+```ts
+interface Handler {
+    readonly mimetype: string;
+    readonly glyph: string;
+    readonly extensions: readonly string[];
+    extract(content: string): MimeSymbol[];
+    validate(content: string): void;
+    symbols(content: string): string;
+    preview(content: string, budget: number): Promise<string>;
+}
+```
+
+In practice handlers extend `BaseHandler` (or `AntlrExtractor`), which provides every method derived from a single `extract(content) → MimeSymbol[]`. Subclasses normally implement `extract` only. Identity (`mimetype`, `glyph`, `extensions`) is injected at construction time from the handler's `package.json` `plurnk` block.
+
+## 2. `package.json` `plurnk` discovery block
+
+```json
+{
+    "plurnk": {
+        "kind": "mimetype",
+        "name": "text/x-python",
+        "glyph": "🐍",
+        "extensions": [".py", ".pyw"]
+    }
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `kind` | `"mimetype"` | yes | Distinguishes mimetype handlers from `"provider"` and `"scheme"` siblings in the plurnk family |
+| `name` | string | yes | The canonical mimetype (`text/markdown`, `application/json`, `text/x-python`, …) |
+| `glyph` | string | no | Single-character display marker; defaults to empty string |
+| `extensions` | string[] | no | Mixed list: entries beginning with `.` are file extensions (lowercased on match); other entries are special filenames matched verbatim (`Dockerfile`, `Makefile`) |
+
+`discover()` scans `node_modules/@plurnk/` for packages with `plurnk.kind === "mimetype"`. Last-loaded wins on mimetype or extension conflicts.
+
+## 3. `MimeSymbol` and `SymbolKind`
+
+```ts
+interface MimeSymbol {
+    name: string;
+    kind: SymbolKind;
+    line: number;        // 1-indexed start
+    endLine: number;     // 1-indexed end (== line for single-line symbols)
+    params?: string[];   // present on functions and methods when names are available
+    level?: number;      // present on heading kinds; 1-6
+}
+
+type SymbolKind =
+    | "class" | "function" | "method" | "field"
+    | "interface" | "enum" | "type" | "module"
+    | "variable" | "constant" | "heading";
+```
+
+### Inclusion policy
+
+Handlers include symbols that are **defined in the content and not confirmed invisible outside their declaring scope**.
+
+- Include: classes, functions, methods, fields, interfaces, enums, types, modules, exported variables/constants, markdown headings.
+- Exclude: imports, exports as standalone symbols, local variables inside function bodies, unexported module-scope variables (in languages with module privacy), function calls, control flow, comments, magic numbers, anonymous declarations.
+- Class members (methods, fields) are always included — they're the API surface even though syntactically inside a class body.
+- When in doubt, include. Only exclude when the language semantics *confirm* the symbol is inaccessible from outside the file.
+
+### Parameters
+
+Functions and methods include `params` when the grammar exposes them:
+
+- Plain names: `["source", "options"]`
+- Destructured: `["{host, port}"]` (raw text)
+- Rest: `["...args"]`
+- Defaults: `["entryRule=\"program\""]` (included in the assignable text)
+
+Omit `params` entirely when the language doesn't expose named parameters.
+
+## 4. Outline format (`symbols` / `format`)
+
+The framework owns outline rendering. Handlers produce structured `MimeSymbol[]`; `format(symbols)` turns it into a string.
+
+**Tree hierarchy:**
+- Heading symbols: nested by `level` field (1–6).
+- Other symbols: nested by line-range containment. A symbol whose `[line, endLine]` is fully inside another's is its child.
+
+**Line rendering:**
+- Heading: `<indent># Name [line]` (hash count = level, indent = tree depth).
+- Other: `<indent>kind name(params)? [line-endLine]` (kind prefix, params if present, range collapses to `[N]` when single-line).
+- Indent unit: two spaces per depth level.
+
+Example:
+```
+class Parser [5-47]
+  method parse(source) [10-20]
+  method load(dir) [22-45]
+function topLevel(a, b) [50-60]
+```
+
+## 5. `preview` — token-budgeted truncation
+
+`Mimetypes.process` accepts `{ budget?: number }`. When unspecified, budget is `Number.POSITIVE_INFINITY` (no truncation — preview equals symbols). The helper does NOT invent a magic default; plurnk-service supplies the real budget per call.
+
+**Budget unit is tokens, never characters.** The tokenize function is injected at `Mimetypes` construction time. The default fallback (`defaultTokenize`) is `Math.ceil(text.length / 2)` — conservative; biased toward overestimation, not the industry-standard `/4` heuristic.
+
+**Truncation strategy (`fit`):**
+1. Render full outline. If it fits, return it.
+2. Drop deepest tree level. Render. Repeat until fits or only roots remain.
+3. If even all-roots overflows, drop trailing root symbols one at a time until fits.
+4. If even a single root overflows, return empty string (surrender — caller may invoke `fitContent` to substitute a raw-content fragment).
+
+**Raw content fallback (`fitContent`):**
+- Used when `extract()` returns `[]` (empty symbols) but the content is non-empty.
+- Iteratively shrinks the content slice to fit `budget` tokens via the same tokenize function, with safety margin and max-iterations clamp.
+
+## 6. `validate`
+
+Default: no-op. Override only for mimetypes with a real syntax check that can fail (e.g., `application/json` throws on malformed JSON).
+
+When `validate` throws inside `Mimetypes.process`, the error propagates to the caller per the error policy (§7).
+
+## 7. Error policy
+
+| Failure | Behavior |
+|---|---|
+| Detection returns null | `{ mimetype: null, symbols: "", preview: "", ok: false }` |
+| Content read fails (path missing/unreadable) | `{ mimetype, symbols: "", preview: "", ok: false }` |
+| Handler package not loadable | `{ mimetype, symbols: "", preview: <raw fallback>, ok: false }` |
+| `validate()` throws | **Propagates** to the caller — contract violation |
+| `extract()` throws | Contained inside `AntlrExtractor` → empty `MimeSymbol[]` → raw-content fallback |
+| `extract()` returns `[]` with non-empty content | Symbols string empty; preview falls back to `fitContent(content, budget)` |
+
+## 8. Detection priority
+
+`detect({ path?, ext?, hint?, content? }, registry)` resolves in strict priority order, highest wins:
+
+1. `hint` — caller asserts a mimetype directly.
+2. `path` basename matches a registered filename (`Dockerfile`, `Makefile`).
+3. `ext` (explicit) or `extname(path)` matches a registered extension (case-insensitive, leading-dot enforced on lookup).
+4. `content` — magic-byte sniffing. **Future hook**; no implementation in v0.1.
+
+Returns the resolved mimetype string or `null`.
+
+## 9. ANTLR extractor
+
+For grammar-backed handlers:
+
+1. Vendor `.g4` files in `grammar/` at the handler repo root.
+2. Add the compiler and runtime to your own devDependencies (the framework declares both as optional peer deps; only ANTLR-backed handlers need them):
+   ```
+   npm install --save-dev antlr-ng@^1.0.10 antlr4ng@^3.0.0
+   ```
+3. Run `npx plurnk-mimetypes-compile` — invokes `antlr-ng -D language=TypeScript -o src/generated --generate-visitor true --generate-listener false grammar/*.g4` and post-processes the output to rewrite `.js` import extensions to `.ts` (so Node's native TS strip works without a separate build pass). Invoke via `npx` so node_modules/.bin/ is on PATH when the spawn happens.
+4. Extend `AntlrExtractor` instead of `BaseHandler`.
+5. Implement `parseTree(content)` (return a parser rule context) and `createVisitor()` (return an `ExtractionVisitor`).
+6. Build the visitor by extending `withExtractor(GeneratedVisitor)` — the mixin adds `symbols`, `inBody`, `addSymbol(kind, name, ctx, params?, extra?)`, and `gateBody(ctx)` to the antlr4ng visitor.
+
+Parse failures and visit-time exceptions are caught by `AntlrExtractor.extract()` and converted to an empty `MimeSymbol[]`, allowing the orchestrator's raw-content fallback to take over.
+
+## 10. Tokenization architecture
+
+The helper never reads any environment variable. Tokenization is a runtime injection from plurnk-service:
+
+```
+plurnk-providers-*           plurnk-service                @plurnk/plurnk-mimetypes
+─────────────────            ──────────────                ────────────────────────
+exports tokenize(text)  ─→   registers from active   ─→    receives at construction
+                              provider                      via { tokenize }
+                              caches by SHA256(text)
+                              budget per call sourced
+                              from PLURNK_ENTRY_SIZE_
+                              DEFAULT_TOKENS env (256)
+```
+
+Handlers never see the tokenize function. The framework uses it internally for `preview` only.
+
+## 11. Public API stability
+
+All exports from `@plurnk/plurnk-mimetypes/index` are stable from `v0.1.0` onward under semver. Internal modules (those not re-exported from `index.ts`) are not part of the stable API and may change between minor versions.

package/bin/plurnk-mimetypes-compile.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { cli } from "../dist/compile.js";
+
+cli(process.argv.slice(2)).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/AntlrExtractor.d.ts

@@ -0,0 +1,8 @@
+import BaseHandler from "./BaseHandler.ts";
+import type { ExtractionVisitor, MimeSymbol } from "./types.ts";
+export default abstract class AntlrExtractor extends BaseHandler {
+    protected abstract parseTree(content: string): unknown;
+    protected abstract createVisitor(): ExtractionVisitor;
+    extract(content: string): MimeSymbol[];
+}
+//# sourceMappingURL=AntlrExtractor.d.ts.map

package/dist/AntlrExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AntlrExtractor.d.ts","sourceRoot":"","sources":["../src/AntlrExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAUhE,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,cAAe,SAAQ,WAAW;IAC5D,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IACtD,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,iBAAiB;IAErD,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;CAiBzC"}

package/dist/AntlrExtractor.js

@@ -0,0 +1,31 @@
+import BaseHandler from "./BaseHandler.js";
+// Abstract base for grammar-backed mimetype handlers. Subclasses supply two
+// methods:
+//   parseTree(content) — construct lexer/parser, return the entry-rule tree.
+//   createVisitor()    — return an ExtractionVisitor (typically built via
+//                        withExtractor(GeneratedVisitor)).
+// extract() orchestrates: parseTree -> createVisitor -> visit -> visitor.symbols.
+// Parse and visit errors are caught and converted to an empty symbol list;
+// callers fall back to a raw-content preview when extraction yields nothing.
+export default class AntlrExtractor extends BaseHandler {
+    extract(content) {
+        let tree;
+        try {
+            tree = this.parseTree(content);
+        }
+        catch {
+            return [];
+        }
+        if (tree === null || tree === undefined)
+            return [];
+        const visitor = this.createVisitor();
+        try {
+            visitor.visit(tree);
+        }
+        catch {
+            return [];
+        }
+        return visitor.symbols;
+    }
+}
+//# sourceMappingURL=AntlrExtractor.js.map

package/dist/AntlrExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AntlrExtractor.js","sourceRoot":"","sources":["../src/AntlrExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAG3C,4EAA4E;AAC5E,WAAW;AACX,6EAA6E;AAC7E,0EAA0E;AAC1E,2DAA2D;AAC3D,kFAAkF;AAClF,2EAA2E;AAC3E,6EAA6E;AAC7E,MAAM,CAAC,OAAO,OAAgB,cAAe,SAAQ,WAAW;IAI5D,OAAO,CAAC,OAAe;QACnB,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACD,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,EAAE,CAAC;QACd,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QAEnD,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACrC,IAAI,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,EAAE,CAAC;QACd,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC;IAC3B,CAAC;CACJ"}

package/dist/BaseHandler.d.ts

@@ -0,0 +1,13 @@
+import type { HandlerMetadata, HandlerOptions, MimeSymbol } from "./types.ts";
+export default class BaseHandler {
+    #private;
+    readonly mimetype: string;
+    readonly glyph: string;
+    readonly extensions: readonly string[];
+    constructor(metadata: HandlerMetadata, options?: HandlerOptions);
+    extract(_content: string): MimeSymbol[];
+    validate(_content: string): void;
+    symbols(content: string): string;
+    preview(content: string, budget: number): Promise<string>;
+}
+//# sourceMappingURL=BaseHandler.d.ts.map

package/dist/BaseHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseHandler.d.ts","sourceRoot":"","sources":["../src/BaseHandler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAc,MAAM,YAAY,CAAC;AAE1F,MAAM,CAAC,OAAO,OAAO,WAAW;;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;gBAG3B,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAE,cAAmB;IAOnE,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE;IAIvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIhC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI1B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGlE"}

package/dist/BaseHandler.js

@@ -0,0 +1,28 @@
+import { defaultTokenize } from "./defaults.js";
+import { format } from "./format.js";
+import { fit } from "./fit.js";
+export default class BaseHandler {
+    mimetype;
+    glyph;
+    extensions;
+    #tokenize;
+    constructor(metadata, options = {}) {
+        this.mimetype = metadata.mimetype;
+        this.glyph = metadata.glyph;
+        this.extensions = Object.freeze([...metadata.extensions]);
+        this.#tokenize = options.tokenize ?? defaultTokenize;
+    }
+    extract(_content) {
+        return [];
+    }
+    validate(_content) {
+        // Default: anything is valid. Override for mimetypes with real syntax.
+    }
+    symbols(content) {
+        return format(this.extract(content));
+    }
+    async preview(content, budget) {
+        return fit(this.extract(content), budget, this.#tokenize);
+    }
+}
+//# sourceMappingURL=BaseHandler.js.map

package/dist/BaseHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseHandler.js","sourceRoot":"","sources":["../src/BaseHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAG/B,MAAM,CAAC,OAAO,OAAO,WAAW;IACnB,QAAQ,CAAS;IACjB,KAAK,CAAS;IACd,UAAU,CAAoB;IAC9B,SAAS,CAAa;IAE/B,YAAY,QAAyB,EAAE,UAA0B,EAAE;QAC/D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IACzD,CAAC;IAED,OAAO,CAAC,QAAgB;QACpB,OAAO,EAAE,CAAC;IACd,CAAC;IAED,QAAQ,CAAC,QAAgB;QACrB,uEAAuE;IAC3E,CAAC;IAED,OAAO,CAAC,OAAe;QACnB,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,MAAc;QACzC,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACJ"}

package/dist/Mimetypes.d.ts

@@ -0,0 +1,33 @@
+import type BaseHandler from "./BaseHandler.ts";
+import type { DetectInput, DiscoverOptions, Discovery, TokenizeFn } from "./types.ts";
+export type HandlerLoader = (packageName: string) => Promise<unknown>;
+export interface MimetypesOptions {
+    tokenize?: TokenizeFn;
+    discoverOptions?: DiscoverOptions;
+    discovery?: Discovery;
+    loader?: HandlerLoader;
+}
+export interface ProcessInput {
+    path?: string;
+    content?: string;
+    ext?: string;
+    hint?: string;
+}
+export interface ProcessOptions {
+    budget?: number;
+}
+export interface ProcessResult {
+    mimetype: string | null;
+    symbols: string;
+    preview: string;
+    ok: boolean;
+}
+export default class Mimetypes {
+    #private;
+    constructor(options?: MimetypesOptions);
+    ready(): Promise<void>;
+    detect(input: DetectInput): Promise<string | null>;
+    getHandler(mimetype: string): Promise<BaseHandler | null>;
+    process(input: ProcessInput, options?: ProcessOptions): Promise<ProcessResult>;
+}
+//# sourceMappingURL=Mimetypes.d.ts.map

package/dist/Mimetypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mimetypes.d.ts","sourceRoot":"","sources":["../src/Mimetypes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EACR,WAAW,EACX,eAAe,EACf,SAAS,EAGT,UAAU,EACb,MAAM,YAAY,CAAC;AAapB,MAAM,MAAM,aAAa,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAItE,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;IAGlC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;CACf;AAMD,MAAM,CAAC,OAAO,OAAO,SAAS;;gBAQd,OAAO,GAAE,gBAAqB;IAUpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKlD,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAuCzD,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;CAwC3F"}

package/dist/Mimetypes.js

@@ -0,0 +1,131 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import fs from "node:fs/promises";
+import { defaultTokenize } from "./defaults.js";
+import { detect } from "./detect.js";
+import { discover } from "./discover.js";
+import { fitContent } from "./fit.js";
+// No default budget in the helper. plurnk-service owns the real default
+// (PLURNK_ENTRY_SIZE_DEFAULT_TOKENS, runtime env, currently 256 tokens for the
+// channel preview portal) and passes it per call. When budget is unspecified
+// here, preview is unbounded — equivalent to symbols. Baking a fallback number
+// would silently shadow the env var and create drift when plurnk-service
+// changes its default.
+const UNBOUNDED_BUDGET = Number.POSITIVE_INFINITY;
+const defaultLoader = (packageName) => import(__rewriteRelativeImportExtension(packageName));
+// Top-level orchestrator. Plurnk-service constructs one of these at boot,
+// injecting its tokenize function. process(path) is the primary entry point;
+// detect() and getHandler() are exposed for callers that want to drive the
+// pipeline manually.
+export default class Mimetypes {
+    #tokenize;
+    #discoverOptions;
+    #loader;
+    #handlerInstances = new Map();
+    #discovery = null;
+    #readyPromise = null;
+    constructor(options = {}) {
+        this.#tokenize = options.tokenize ?? defaultTokenize;
+        this.#discoverOptions = options.discoverOptions ?? {};
+        this.#loader = options.loader ?? defaultLoader;
+        if (options.discovery !== undefined)
+            this.#discovery = options.discovery;
+    }
+    // Eagerly run discovery. Safe to call multiple times — subsequent calls
+    // share the same in-flight promise. Optional: every public method that
+    // needs discovery awaits this internally.
+    async ready() {
+        if (this.#discovery !== null)
+            return;
+        if (this.#readyPromise !== null)
+            return this.#readyPromise;
+        this.#readyPromise = (async () => {
+            this.#discovery = await discover(this.#discoverOptions);
+        })();
+        return this.#readyPromise;
+    }
+    async detect(input) {
+        await this.ready();
+        return detect(input, this.#discovery.registry);
+    }
+    async getHandler(mimetype) {
+        await this.ready();
+        const cached = this.#handlerInstances.get(mimetype);
+        if (cached !== undefined)
+            return cached;
+        const info = this.#discovery.handlers.get(mimetype);
+        if (info === undefined)
+            return null;
+        let mod;
+        try {
+            mod = await this.#loader(info.packageName);
+        }
+        catch {
+            return null;
+        }
+        if (typeof mod !== "object" || mod === null)
+            return null;
+        const HandlerClass = mod.default;
+        if (typeof HandlerClass !== "function")
+            return null;
+        const metadata = {
+            mimetype: info.mimetype,
+            glyph: info.glyph,
+            extensions: info.extensions,
+        };
+        const handlerOptions = { tokenize: this.#tokenize };
+        const Ctor = HandlerClass;
+        const handler = new Ctor(metadata, handlerOptions);
+        this.#handlerInstances.set(mimetype, handler);
+        return handler;
+    }
+    // The pipeline. Detection -> content read -> handler resolve -> validate ->
+    // extract -> symbols -> preview. Errors are routed per policy:
+    //   * detection fails or content read fails -> ok:false, empty strings
+    //   * handler missing -> ok:false, raw-content preview as fallback
+    //   * validate throws -> propagates (caller's contract; bug in content or handler)
+    //   * extract throws -> contained inside handler -> empty symbols -> raw fallback
+    async process(input, options = {}) {
+        const budget = options.budget ?? UNBOUNDED_BUDGET;
+        const mimetype = await this.detect(input);
+        if (mimetype === null) {
+            return { mimetype: null, symbols: "", preview: "", ok: false };
+        }
+        const content = await this.#resolveContent(input);
+        if (content === null) {
+            return { mimetype, symbols: "", preview: "", ok: false };
+        }
+        const handler = await this.getHandler(mimetype);
+        if (handler === null) {
+            const preview = await fitContent(content, budget, this.#tokenize);
+            return { mimetype, symbols: "", preview, ok: false };
+        }
+        // Validate errors propagate per error policy — caller's contract.
+        handler.validate(content);
+        const symbols = handler.symbols(content);
+        let preview = await handler.preview(content, budget);
+        if (preview === "" && content !== "") {
+            preview = await fitContent(content, budget, this.#tokenize);
+        }
+        return { mimetype, symbols, preview, ok: true };
+    }
+    async #resolveContent(input) {
+        if (input.content !== undefined)
+            return input.content;
+        if (input.path === undefined || input.path === "")
+            return null;
+        try {
+            return await fs.readFile(input.path, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=Mimetypes.js.map

package/dist/Mimetypes.js.map

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

package/dist/compile.d.ts

@@ -0,0 +1,9 @@
+export interface CompileOptions {
+    grammarDir?: string;
+    outDir?: string;
+    cwd?: string;
+}
+export declare function runCompile(opts?: CompileOptions): Promise<void>;
+export declare function rewriteImports(dir: string): Promise<void>;
+export declare function cli(argv: string[]): Promise<void>;
+//# sourceMappingURL=compile.d.ts.map

package/dist/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD,wBAAsB,UAAU,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BzE;AA6BD,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB/D;AAED,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAavD"}