@untangle-code/cli 0.0.0-stage → 0.1.1

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,152 @@
+# Third-party licenses — @untangle-code/cli
+
+Generated by `pnpm third-party-licenses` from this package's installed
+production dependency tree: transitive `dependencies`, across
+workspace edges, with no `devDependencies` included. The generator reads
+each resolved package's `package.json` in `node_modules`; nothing is maintained by hand
+or estimated.
+
+Do not edit manually: `pnpm third-party-licenses --check` fails on drift,
+and `pnpm check-publishable` rejects packages without a current file.
+
+This file exists because `docs/BUILD_PLAN.md`, risk R6, makes
+per-package `THIRD_PARTY_LICENSES.md` a release gate for npm publication.
+
+Untangle itself is **AGPL-3.0-only** (see `LICENSE` and `NOTICE` in
+this package). The packages below are third-party works; their own
+licenses and copyright notices continue to apply unchanged. Workspace
+packages (`@untangle-code/*`) are not listed here; they belong to the same
+work and use the same AGPL-3.0-only license.
+
+## Production dependencies (transitive, 66)
+
+| Package | Version | License | Project |
+| --- | --- | --- | --- |
+| `@ast-grep/lang-python` | 0.0.6 | ISC | — |
+| `@ast-grep/napi` | 0.45.3 | MIT | <https://ast-grep.github.io> |
+| `@ast-grep/setup-lang` | 0.0.6 | ISC | — |
+| `@babel/helper-string-parser` | 7.29.7 | MIT | <https://babel.dev/docs/en/next/babel-helper-string-parser> |
+| `@babel/helper-validator-identifier` | 7.29.7 | MIT | <https://github.com/babel/babel> |
+| `@babel/parser` | 7.29.9 | MIT | <https://babel.dev/docs/en/next/babel-parser> |
+| `@babel/types` | 7.29.8 | MIT | <https://babel.dev/docs/en/next/babel-types> |
+| `@jridgewell/sourcemap-codec` | 1.6.0 | MIT | <https://github.com/jridgewell/sourcemaps/tree/main/packages/sourcemap-codec> |
+| `@lancedb/lancedb` | 0.30.0 | Apache-2.0 | <https://github.com/lancedb/lancedb> |
+| `@modelcontextprotocol/core` | 2.0.0 | MIT | <https://modelcontextprotocol.io> |
+| `@modelcontextprotocol/server` | 2.0.0 | MIT | <https://modelcontextprotocol.io> |
+| `@nodable/entities` | 3.0.0 | MIT | <https://github.com/nodable/val-parsers> |
+| `@swc/helpers` | 0.5.24 | Apache-2.0 | <https://swc.rs> |
+| `@types/command-line-args` | 5.2.3 | MIT | <https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/command-line-args> |
+| `@types/command-line-usage` | 5.0.4 | MIT | <https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/command-line-usage> |
+| `@types/node` | 20.19.43 | MIT | <https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node> |
+| `@vue/compiler-core` | 3.5.44 | MIT | <https://github.com/vuejs/core/tree/main/packages/compiler-core#readme> |
+| `@vue/compiler-dom` | 3.5.44 | MIT | <https://github.com/vuejs/core/tree/main/packages/compiler-dom#readme> |
+| `@vue/compiler-sfc` | 3.5.44 | MIT | <https://github.com/vuejs/core/tree/main/packages/compiler-sfc#readme> |
+| `@vue/compiler-ssr` | 3.5.44 | MIT | <https://github.com/vuejs/core/tree/main/packages/compiler-ssr#readme> |
+| `@vue/shared` | 3.5.44 | MIT | <https://github.com/vuejs/core/tree/main/packages/shared#readme> |
+| `ansi-styles` | 4.3.0 | MIT | `chalk/ansi-styles` |
+| `anynum` | 1.0.1 | MIT | <https://github.com/NaturalIntelligence/anynum> |
+| `apache-arrow` | 18.1.0 | Apache-2.0 | <https://github.com/apache/arrow/blob/main/js/README.md> |
+| `array-back` | 3.1.0 | MIT | <https://github.com/75lb/array-back> |
+| `array-back` | 6.2.3 | MIT | <https://github.com/75lb/array-back> |
+| `chalk` | 4.1.2 | MIT | `chalk/chalk` |
+| `chalk-template` | 0.4.0 | MIT | `chalk/chalk-template` |
+| `color-convert` | 2.0.1 | MIT | `Qix-/color-convert` |
+| `color-name` | 1.1.4 | MIT | <https://github.com/colorjs/color-name> |
+| `command-line-args` | 5.2.1 | MIT | <https://github.com/75lb/command-line-args> |
+| `command-line-usage` | 7.0.4 | MIT | <https://github.com/75lb/command-line-usage> |
+| `entities` | 7.0.1 | BSD-2-Clause | <https://github.com/fb55/entities> |
+| `estree-walker` | 2.0.2 | MIT | <https://github.com/Rich-Harris/estree-walker> |
+| `fast-xml-builder` | 1.3.1 | MIT | <https://github.com/NaturalIntelligence/fast-xml-builder> |
+| `fast-xml-parser` | 5.11.1 | MIT | <https://github.com/NaturalIntelligence/fast-xml-parser> |
+| `find-replace` | 3.0.0 | MIT | <https://github.com/75lb/find-replace> |
+| `flatbuffers` | 24.12.23 | Apache-2.0 | <https://google.github.io/flatbuffers/> |
+| `has-flag` | 4.0.0 | MIT | `sindresorhus/has-flag` |
+| `is-unsafe` | 2.0.2 | MIT | <https://github.com/NaturalIntelligence/is-unsafe> |
+| `json-bignum` | 0.0.3 | MIT | <https://github.com/datalanche/json-bignum> |
+| `lodash.camelcase` | 4.3.0 | MIT | <https://lodash.com/> |
+| `magic-string` | 0.30.21 | MIT | <https://github.com/Rich-Harris/magic-string> |
+| `nanoid` | 3.3.20 | MIT | `ai/nanoid` |
+| `node-addon-api` | 8.9.2 | MIT | <https://github.com/nodejs/node-addon-api> |
+| `node-gyp-build` | 4.8.4 | MIT | <https://github.com/prebuild/node-gyp-build> |
+| `path-expression-matcher` | 1.6.2 | MIT | <https://github.com/NaturalIntelligence/path-expression-matcher#readme> |
+| `picocolors` | 1.1.1 | ISC | `alexeyraspopov/picocolors` |
+| `postcss` | 8.5.31 | MIT | <https://postcss.org/> |
+| `reflect-metadata` | 0.2.2 | Apache-2.0 | <http://rbuckton.github.io/reflect-metadata> |
+| `smol-toml` | 1.8.0 | BSD-3-Clause | `github:squirrelchat/smol-toml` |
+| `source-map-js` | 1.2.2 | BSD-3-Clause | <https://github.com/7rulnik/source-map-js> |
+| `strnum` | 2.4.2 | MIT | <https://github.com/NaturalIntelligence/strnum> |
+| `supports-color` | 7.2.0 | MIT | `chalk/supports-color` |
+| `table-layout` | 4.1.1 | MIT | <https://github.com/75lb/table-layout> |
+| `tree-sitter` | 0.21.1 | MIT | <http://github.com/tree-sitter/node-tree-sitter> |
+| `tree-sitter-javascript` | 0.23.1 | MIT | <https://github.com/tree-sitter/tree-sitter-javascript> |
+| `tree-sitter-typescript` | 0.23.2 | MIT | <https://github.com/tree-sitter/tree-sitter-typescript> |
+| `tslib` | 2.8.1 | 0BSD | <https://www.typescriptlang.org/> |
+| `typical` | 4.0.0 | MIT | <https://github.com/75lb/typical> |
+| `typical` | 7.3.0 | MIT | <https://github.com/75lb/typical> |
+| `undici-types` | 6.21.0 | MIT | <https://undici.nodejs.org> |
+| `wordwrapjs` | 5.1.1 | MIT | <https://github.com/75lb/wordwrapjs> |
+| `xml-naming` | 0.3.0 | MIT | <https://github.com/NaturalIntelligence/xml-naming> |
+| `yaml` | 2.9.0 | ISC | <https://eemeli.org/yaml/> |
+| `zod` | 4.5.4 | MIT | <https://zod.dev> |
+
+The allowlist (MIT / Apache-2.0 / BSD / ISC / …) is checked by
+`scripts/check-licenses.mjs` against this exact tree on every run;
+the GPL family is excluded (architecture.md §2.4, BUILD_PLAN R6).
+
+## Embedded tree-sitter grammars (12)
+
+The `@ast-grep/lang-*` packages distribute third-party tree-sitter grammars:
+their `src/parser.c` files are byte-identical to the listed grammar versions,
+as verified by `pnpm grammar-provenance --update`
+(field `parserMatchesGrammar`). However, their own `LICENSE` only names
+`Copyright (c) 2025 ast-grep`; the grammar authors are not listed there.
+Untangle therefore records their notices here.
+
+| Language package | Dependency | Grammar | License | Copyright notice |
+| --- | --- | --- | --- | --- |
+| `@ast-grep/lang-bash` | optional; install separately | `tree-sitter-bash` 0.25.1 | MIT | Copyright (c) 2017 Max Brunsfeld |
+| `@ast-grep/lang-c` | optional; install separately | `tree-sitter-c` 0.24.1 | MIT | Copyright (c) 2014 Max Brunsfeld |
+| `@ast-grep/lang-cpp` | optional; install separately | `tree-sitter-cpp` 0.23.4 | MIT | Copyright (c) 2014 Max Brunsfeld |
+| `@ast-grep/lang-csharp` | optional; install separately | `tree-sitter-c-sharp` 0.23.1 | MIT | Copyright (c) 2014-2023 Max Brunsfeld, Damien Guard, Amaan Qureshi, and contributors. |
+| `@ast-grep/lang-go` | optional; install separately | `tree-sitter-go` 0.25.0 | MIT | Copyright (c) 2014 Max Brunsfeld |
+| `@ast-grep/lang-java` | optional; install separately | `tree-sitter-java` 0.23.5 | MIT | Copyright (c) 2017 Ayman Nadeem |
+| `@ast-grep/lang-kotlin` | optional; install separately | `tree-sitter-kotlin` 0.3.8 | MIT | Copyright (c) 2019 fwcd |
+| `@ast-grep/lang-php` | optional; install separately | `tree-sitter-php` 0.24.2 | MIT | Copyright (c) 2017 Josh Vera, GitHub<br>Copyright (c) 2019 Max Brunsfeld, Amaan Qureshi, Christian Frøystad, Caleb White |
+| `@ast-grep/lang-python` | Dependency | `tree-sitter-python` 0.25.0 | MIT | Copyright (c) 2016 Max Brunsfeld |
+| `@ast-grep/lang-ruby` | optional; install separately | `tree-sitter-ruby` 0.23.1 | MIT | Copyright (c) 2016 Rob Rix |
+| `@ast-grep/lang-rust` | optional; install separately | `tree-sitter-rust` 0.23.2 | MIT | Copyright (c) 2017 Maxim Sokolov |
+| `@ast-grep/lang-swift` | optional; install separately | `tree-sitter-swift` 0.7.1 | MIT | Copyright (c) 2021 alex-pinkus |
+
+**An unresolved question that Untangle cannot decide.** All language packages above
+declare `"license": "ISC"` in `package.json`, but include an **MIT** license text.
+Both declarations cannot apply simultaneously. Which declaration ast-grep intends
+cannot be determined externally; this file records
+the contradiction instead of inventing a resolution. For the embedded
+grammars, the license is unambiguous: the table uses the license text
+inside each grammar version's tarball rather than its
+registry metadata's `license` field.
+
+Packages marked *optional* are not included in an Untangle installation:
+they are optional `peerDependencies`, which npm
+does not install automatically. They are listed for users who
+add them to enable the corresponding language.
+
+## LanceDB platform-native runtime packages
+
+The SDK declares the following native optional dependencies. Package names, pinned versions
+and SPDX license declarations come from the published version manifests recorded with hashes
+in `scripts/lancedb-native-provenance.json`. Every native variant actually resolved on the
+generating platform is checked against that metadata; its dependencies are included above.
+This table is a declaration inventory, not a claim that all seven binaries were installed or
+inspected. The release's installed production SBOM records the actual platform selection.
+Upstream package license files and notices continue to apply and remain distributed by npm.
+
+| Native package | Version | Declared license | Published manifest |
+| --- | --- | --- | --- |
+| `@lancedb/lancedb-darwin-arm64` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-darwin-arm64/0.30.0> |
+| `@lancedb/lancedb-linux-arm64-gnu` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-linux-arm64-gnu/0.30.0> |
+| `@lancedb/lancedb-linux-arm64-musl` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-linux-arm64-musl/0.30.0> |
+| `@lancedb/lancedb-linux-x64-gnu` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-linux-x64-gnu/0.30.0> |
+| `@lancedb/lancedb-linux-x64-musl` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-linux-x64-musl/0.30.0> |
+| `@lancedb/lancedb-win32-arm64-msvc` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-win32-arm64-msvc/0.30.0> |
+| `@lancedb/lancedb-win32-x64-msvc` | 0.30.0 | Apache-2.0 | <https://registry.npmjs.org/%40lancedb%2Flancedb-win32-x64-msvc/0.30.0> |

package/dist/cli/args.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Ein kleiner, abhaengigkeitsfreier Argumentparser.
+ *
+ * WARUM KEINE BIBLIOTHEK: Die Oberflaeche ist der Ort, an dem E4 am
+ * leichtesten verletzt wird — die meisten Parser ignorieren eine unbekannte
+ * Option stillschweigend oder schieben sie in die Positionsargumente. Dann
+ * tippt ein Nutzer `--explaine` und bekommt eine Ausgabe ohne Zerlegung, ohne
+ * je zu erfahren, dass seine Option nie ankam. Dieser Parser LEHNT jede
+ * unbekannte Option ab.
+ *
+ * Unterstuetzt: `--name`, `--name=wert`, `--name wert`, `-k` (Kurzform),
+ * `--no-name` (Boolesche Negation), `--` (alles danach ist Positionsargument).
+ */
+export type FlagKind = "boolean" | "string" | "number" | "list" | "boolean-or-number";
+export interface FlagSpec {
+    readonly kind: FlagKind;
+    /** Einbuchstabige Kurzform ohne Bindestrich, z. B. "n". */
+    readonly alias?: string;
+    /** Was hinter der Option steht, z. B. "N" oder "MUSTER". */
+    readonly placeholder?: string;
+    /** Eine Zeile Hilfetext. */
+    readonly describe: string;
+    /** Nur zur Anzeige in `--help`. */
+    readonly defaultLabel?: string;
+}
+export type FlagSpecs = Readonly<Record<string, FlagSpec>>;
+export type FlagValue = boolean | string | number | readonly string[];
+export interface ParsedArgs {
+    readonly positionals: readonly string[];
+    readonly flags: Readonly<Record<string, FlagValue>>;
+}
+/**
+ * Zerlegt `argv` gegen `specs`. Wirft {@link UsageError} bei allem, was nicht
+ * eindeutig ist — unbekannte Option, fehlender Wert, keine Zahl.
+ */
+export declare function parseArgs(argv: readonly string[], specs: FlagSpecs): ParsedArgs;
+export declare function boolFlag(args: ParsedArgs, name: string, fallback?: boolean): boolean;
+export declare function stringFlag(args: ParsedArgs, name: string): string | undefined;
+export declare function numberFlag(args: ParsedArgs, name: string): number | undefined;
+export declare function listFlag(args: ParsedArgs, name: string): string[];
+/**
+ * Liest eine Option, deren Wert aus einer festen Menge stammen MUSS.
+ * Ein Tippfehler wird abgelehnt statt auf den Default zurueckzufallen.
+ */
+export declare function enumFlag<T extends string>(args: ParsedArgs, name: string, allowed: readonly T[], fallback: T): T;
+/** Eine ganze, nicht-negative Zahl — oder eine klare Absage. */
+export declare function integerFlag(args: ParsedArgs, name: string, fallback: number): number;
+//# sourceMappingURL=args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAEtF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE3D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACrD;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAiI/E;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAGlF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAGjE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,QAAQ,EAAE,CAAC,GACV,CAAC,CAQH;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUpF"}

package/dist/cli/args.js

@@ -0,0 +1,167 @@
+/**
+ * Ein kleiner, abhaengigkeitsfreier Argumentparser.
+ *
+ * WARUM KEINE BIBLIOTHEK: Die Oberflaeche ist der Ort, an dem E4 am
+ * leichtesten verletzt wird — die meisten Parser ignorieren eine unbekannte
+ * Option stillschweigend oder schieben sie in die Positionsargumente. Dann
+ * tippt ein Nutzer `--explaine` und bekommt eine Ausgabe ohne Zerlegung, ohne
+ * je zu erfahren, dass seine Option nie ankam. Dieser Parser LEHNT jede
+ * unbekannte Option ab.
+ *
+ * Unterstuetzt: `--name`, `--name=wert`, `--name wert`, `-k` (Kurzform),
+ * `--no-name` (Boolesche Negation), `--` (alles danach ist Positionsargument).
+ */
+import { UsageError } from "./exit.js";
+function isNegatedBoolean(token) {
+    return token.startsWith("--no-");
+}
+/**
+ * Zerlegt `argv` gegen `specs`. Wirft {@link UsageError} bei allem, was nicht
+ * eindeutig ist — unbekannte Option, fehlender Wert, keine Zahl.
+ */
+export function parseArgs(argv, specs) {
+    const byAlias = new Map();
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.alias !== undefined)
+            byAlias.set(spec.alias, name);
+    }
+    const positionals = [];
+    const flags = {};
+    let sawTerminator = false;
+    const resolve = (token) => {
+        const bare = token.startsWith("--") ? token.slice(2) : token.slice(1);
+        const name = token.startsWith("--") ? bare : (byAlias.get(bare) ?? bare);
+        const spec = specs[name];
+        if (spec === undefined) {
+            throw new UsageError(`Unknown option "${token}".`, "See `--help` for this command's supported options.");
+        }
+        return { name, spec };
+    };
+    const assign = (name, spec, raw) => {
+        if (spec.kind === "number" || spec.kind === "boolean-or-number") {
+            const value = Number(raw);
+            if (!Number.isFinite(value)) {
+                throw new UsageError(`Option "--${name}" requires a number; received "${raw}".`, `Example: --${name}=10`);
+            }
+            flags[name] = value;
+            return;
+        }
+        if (spec.kind === "list") {
+            const previous = flags[name];
+            const list = Array.isArray(previous) ? [...previous] : [];
+            list.push(raw);
+            flags[name] = list;
+            return;
+        }
+        flags[name] = raw;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (sawTerminator) {
+            positionals.push(token);
+            continue;
+        }
+        if (token === "--") {
+            sawTerminator = true;
+            continue;
+        }
+        if (token === "-" || !token.startsWith("-")) {
+            positionals.push(token);
+            continue;
+        }
+        // --name=wert
+        const equals = token.indexOf("=");
+        if (token.startsWith("--") && equals > 2) {
+            const head = token.slice(0, equals);
+            const raw = token.slice(equals + 1);
+            const { name, spec } = resolve(head);
+            if (spec.kind === "boolean") {
+                if (raw !== "true" && raw !== "false") {
+                    throw new UsageError(`Option "--${name}" is a switch accepting only "true" or "false"; received "${raw}".`, `Use --${name} or --no-${name}.`);
+                }
+                flags[name] = raw === "true";
+                continue;
+            }
+            if (spec.kind === "boolean-or-number" && (raw === "true" || raw === "false")) {
+                flags[name] = raw === "true";
+                continue;
+            }
+            assign(name, spec, raw);
+            continue;
+        }
+        // --no-name
+        if (isNegatedBoolean(token)) {
+            const name = token.slice(5);
+            const spec = specs[name];
+            if (spec === undefined || (spec.kind !== "boolean" && spec.kind !== "boolean-or-number")) {
+                throw new UsageError(`Unknown switch "${token}".`, "See `--help` for this command's supported options.");
+            }
+            flags[name] = false;
+            continue;
+        }
+        const { name, spec } = resolve(token);
+        if (spec.kind === "boolean") {
+            flags[name] = true;
+            continue;
+        }
+        if (spec.kind === "boolean-or-number") {
+            const next = argv[i + 1];
+            if (next !== undefined && next !== "" && Number.isFinite(Number(next))) {
+                i++;
+                assign(name, spec, next);
+            }
+            else {
+                flags[name] = true;
+            }
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined ||
+            (next.startsWith("-") && next !== "-" && Number.isNaN(Number(next)))) {
+            throw new UsageError(`Option "--${name}" requires a value.`, `Use --${name}=<${spec.placeholder ?? "value"}> or --${name} <${spec.placeholder ?? "value"}>.`);
+        }
+        i++;
+        assign(name, spec, next);
+    }
+    return { positionals, flags };
+}
+/* --- Typisierte Leser. Sie erfinden nichts: fehlt ein Wert, kommt der Default. */
+export function boolFlag(args, name, fallback = false) {
+    const value = args.flags[name];
+    return typeof value === "boolean" ? value : fallback;
+}
+export function stringFlag(args, name) {
+    const value = args.flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+export function numberFlag(args, name) {
+    const value = args.flags[name];
+    return typeof value === "number" ? value : undefined;
+}
+export function listFlag(args, name) {
+    const value = args.flags[name];
+    return Array.isArray(value) ? [...value] : [];
+}
+/**
+ * Liest eine Option, deren Wert aus einer festen Menge stammen MUSS.
+ * Ein Tippfehler wird abgelehnt statt auf den Default zurueckzufallen.
+ */
+export function enumFlag(args, name, allowed, fallback) {
+    const value = stringFlag(args, name);
+    if (value === undefined)
+        return fallback;
+    if (allowed.includes(value))
+        return value;
+    throw new UsageError(`Option "--${name}" does not support value "${value}" is not supported.`, `Choose one of: ${allowed.join(", ")}.`);
+}
+/** Eine ganze, nicht-negative Zahl — oder eine klare Absage. */
+export function integerFlag(args, name, fallback) {
+    const value = numberFlag(args, name);
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 0) {
+        throw new UsageError(`Option "--${name}" requires an integer >= 0; received "${String(value)}".`, `Example: --${name}=5`);
+    }
+    return value;
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/args.js.map

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

package/dist/cli/command.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Der Vertrag eines Unterbefehls und die Hilfe-Ausgabe.
+ *
+ * Die Hilfe wird AUS DER SPEZIFIKATION erzeugt, nicht danebengeschrieben.
+ * Eine handgepflegte Hilfe ist die erste Stelle, an der ein Werkzeug luegt:
+ * die Option verschwindet, der Text bleibt. Hier kann das nicht passieren —
+ * dieselbe `FlagSpecs`, die der Parser akzeptiert, erzeugt den Text.
+ */
+import type { FlagSpecs, ParsedArgs } from "./args.js";
+import type { Io } from "./io.js";
+export interface CommandContext {
+    readonly io: Io;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Wird bei SIGINT/SIGTERM ausgeloest; jeder Port bekommt ihn gereicht. */
+    readonly signal: AbortSignal;
+}
+export interface CommandSpec {
+    readonly name: string;
+    /**
+     * Das Modul, das die FAEHIGKEIT dieses Befehls enthaelt — als Spezifikator
+     * relativ zu `apps/cli/src`, genau so geschrieben, wie ihn ein Import
+     * traegt (z. B. `commands/init/index.js`).
+     *
+     * Warum eine Zeichenkette und nicht „das ergibt sich doch aus dem Import":
+     * WEIL ES SICH NICHT ERGAB. Bis WP-218 lagen zwei Module namens `init`
+     * nebeneinander — `commands/init.ts`, ein Stub ohne Erkennung, und
+     * `commands/init/index.ts`, die fertige, getestete Implementierung. Der
+     * Einstiegspunkt importierte den Stub. Alles uebersetzte, alle Tests
+     * liefen gruen, und das ausgelieferte Binaer tat etwas anderes als das,
+     * was gebaut worden war. Ein Import allein KANN diesen Fehler nicht
+     * melden, weil beide Pfade gueltig sind.
+     *
+     * Mit diesem Feld ist die Zuordnung eine BEHAUPTUNG, die sich pruefen
+     * laesst: `command-wiring.test.ts` laedt das genannte Modul und verlangt,
+     * dass der registrierte Befehl DASSELBE OBJEKT ist, das dieses Modul
+     * ausliefert — und dass kein zweites Modul im Baum einen Befehl anbietet,
+     * der nirgends registriert ist.
+     */
+    readonly implementedBy: string;
+    /** Eine Zeile fuer die Uebersicht in `untangle --help`. */
+    readonly summary: string;
+    /** Aufrufform, z. B. `untangle query <text> [optionen]`. */
+    readonly usage: string;
+    /** Absaetze, die den Befehl EHRLICH beschreiben — auch seine Grenzen. */
+    readonly details?: readonly string[];
+    readonly flags: FlagSpecs;
+    readonly examples?: readonly string[];
+    /** Welche Exit-Codes dieser Befehl belegt, jeweils mit Bedeutung. */
+    readonly exitCodes?: readonly (readonly [number, string])[];
+    /**
+     * True, wenn der Befehl angelegt, seine Faehigkeit aber noch nicht gebaut
+     * ist (siehe `commands/unavailable.ts`).
+     *
+     * Das Merkmal steht hier und nicht in einer Liste im Einstiegspunkt, weil
+     * eine solche Liste driftet: als `watch` gebaut wurde, blieb sie stehen und
+     * behauptete weiter, es fehle. Ein Befehl traegt seinen Stand selbst.
+     */
+    readonly notYetBuilt?: boolean;
+}
+export interface Command {
+    readonly spec: CommandSpec;
+    run(ctx: CommandContext, args: ParsedArgs): Promise<number>;
+}
+/** Rendert `--help` eines Unterbefehls. Deterministisch: Optionen codepoint-sortiert. */
+export declare function renderCommandHelp(spec: CommandSpec): string;
+/** Weicher Zeilenumbruch auf `width` Zeichen; bricht nie mitten im Wort. */
+export declare function wrap(text: string, width: number): string[];
+//# sourceMappingURL=command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7D;AAgBD,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAwC3D;AAED,4EAA4E;AAC5E,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB1D"}

package/dist/cli/command.js

@@ -0,0 +1,82 @@
+/**
+ * Der Vertrag eines Unterbefehls und die Hilfe-Ausgabe.
+ *
+ * Die Hilfe wird AUS DER SPEZIFIKATION erzeugt, nicht danebengeschrieben.
+ * Eine handgepflegte Hilfe ist die erste Stelle, an der ein Werkzeug luegt:
+ * die Option verschwindet, der Text bleibt. Hier kann das nicht passieren —
+ * dieselbe `FlagSpecs`, die der Parser akzeptiert, erzeugt den Text.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+function padEnd(text, width) {
+    return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+/** Die Optionszeile einer Option, z. B. `-n, --limit=N`. */
+function flagLabel(name, spec) {
+    const short = spec.alias === undefined ? "    " : `-${spec.alias}, `;
+    const value = spec.kind === "boolean" || spec.kind === "boolean-or-number"
+        ? ""
+        : `=<${spec.placeholder ?? "value"}>`;
+    return `${short}--${name}${value}`;
+}
+/** Rendert `--help` eines Unterbefehls. Deterministisch: Optionen codepoint-sortiert. */
+export function renderCommandHelp(spec) {
+    const lines = [];
+    lines.push(`untangle ${spec.name} — ${spec.summary}`, "");
+    lines.push("USAGE", `  ${spec.usage}`, "");
+    if (spec.details !== undefined && spec.details.length > 0) {
+        lines.push("DESCRIPTION");
+        for (const paragraph of spec.details) {
+            for (const wrapped of wrap(paragraph, 76))
+                lines.push(`  ${wrapped}`);
+            lines.push("");
+        }
+    }
+    const names = Object.keys(spec.flags).sort(compareCodepoints);
+    if (names.length > 0) {
+        lines.push("OPTIONS");
+        const labels = names.map((name) => flagLabel(name, spec.flags[name]));
+        const width = Math.max(...labels.map((l) => l.length));
+        for (let i = 0; i < names.length; i++) {
+            const name = names[i];
+            const flag = spec.flags[name];
+            const suffix = flag.defaultLabel === undefined ? "" : ` (default: ${flag.defaultLabel})`;
+            lines.push(`  ${padEnd(labels[i], width)}  ${flag.describe}${suffix}`);
+        }
+        lines.push("");
+    }
+    if (spec.examples !== undefined && spec.examples.length > 0) {
+        lines.push("EXAMPLES");
+        for (const example of spec.examples)
+            lines.push(`  ${example}`);
+        lines.push("");
+    }
+    if (spec.exitCodes !== undefined && spec.exitCodes.length > 0) {
+        lines.push("EXIT-CODES");
+        for (const [code, meaning] of spec.exitCodes)
+            lines.push(`  ${String(code)}  ${meaning}`);
+        lines.push("");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+/** Weicher Zeilenumbruch auf `width` Zeichen; bricht nie mitten im Wort. */
+export function wrap(text, width) {
+    const words = text.split(/\s+/u).filter((w) => w.length > 0);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= width) {
+            current = `${current} ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    return lines.length === 0 ? [""] : lines;
+}
+//# sourceMappingURL=command.js.map

package/dist/cli/command.js.map

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

package/dist/cli/deadline.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Eine Frist um einen Portaufruf.
+ *
+ * WARUM DIE OBERFLAECHE EINE EIGENE FRIST BRAUCHT, obwohl jeder Adapter schon
+ * eine hat: die Fristen der Adapter sind fuer den INDEXLAUF bemessen, und dort
+ * ist Durchhalten mehr wert als Tempo. Gemessen an einem ausgelasteten Ollama
+ * wiederholt die Bereitschaftsfolge des Embedding-Adapters ihren Zeitueberlauf
+ * mit Backoff und meldet den Fehlschlag erst nach ueber DREI MINUTEN. Fuer
+ * einen Menschen am Terminal, der eine Frage gestellt hat, ist das kaputt.
+ *
+ * Die Frist der Oberflaeche kuerzt nichts weg und verschweigt nichts: ein
+ * abgebrochener Aufruf ist ein FEHLSCHLAG mit eigenem, benanntem Grund — nie
+ * ein leeres Ergebnis, das wie „nichts gefunden" aussieht (BUILD_PLAN E4).
+ */
+/** Ergebnis eines Laufs mit Frist. `timedOut` unterscheidet Frist von Fehler. */
+export type DeadlineOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly timedOut: boolean;
+    readonly error: unknown;
+};
+/**
+ * Fuehrt `work` mit einer eigenen Frist aus und reicht ihm dafuer ein Signal.
+ *
+ * Das Signal des Aufrufers bleibt wirksam: ein Strg-C bricht sofort ab, nicht
+ * erst nach der Frist. `work` MUSS das gereichte Signal durchreichen — sonst
+ * kehrt der Aufruf zwar zurueck, laeuft aber im Hintergrund weiter (siehe
+ * `main()` in index.ts, das den Prozess deshalb ausdruecklich beendet).
+ */
+export declare function withDeadline<T>(work: (signal: AbortSignal) => Promise<T>, timeoutMs: number, outerSignal: AbortSignal): Promise<DeadlineOutcome<T>>;
+//# sourceMappingURL=deadline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/cli/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,iFAAiF;AACjF,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACzC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAuB7B"}

package/dist/cli/deadline.js

@@ -0,0 +1,49 @@
+/**
+ * Eine Frist um einen Portaufruf.
+ *
+ * WARUM DIE OBERFLAECHE EINE EIGENE FRIST BRAUCHT, obwohl jeder Adapter schon
+ * eine hat: die Fristen der Adapter sind fuer den INDEXLAUF bemessen, und dort
+ * ist Durchhalten mehr wert als Tempo. Gemessen an einem ausgelasteten Ollama
+ * wiederholt die Bereitschaftsfolge des Embedding-Adapters ihren Zeitueberlauf
+ * mit Backoff und meldet den Fehlschlag erst nach ueber DREI MINUTEN. Fuer
+ * einen Menschen am Terminal, der eine Frage gestellt hat, ist das kaputt.
+ *
+ * Die Frist der Oberflaeche kuerzt nichts weg und verschweigt nichts: ein
+ * abgebrochener Aufruf ist ein FEHLSCHLAG mit eigenem, benanntem Grund — nie
+ * ein leeres Ergebnis, das wie „nichts gefunden" aussieht (BUILD_PLAN E4).
+ */
+/**
+ * Fuehrt `work` mit einer eigenen Frist aus und reicht ihm dafuer ein Signal.
+ *
+ * Das Signal des Aufrufers bleibt wirksam: ein Strg-C bricht sofort ab, nicht
+ * erst nach der Frist. `work` MUSS das gereichte Signal durchreichen — sonst
+ * kehrt der Aufruf zwar zurueck, laeuft aber im Hintergrund weiter (siehe
+ * `main()` in index.ts, das den Prozess deshalb ausdruecklich beendet).
+ */
+export async function withDeadline(work, timeoutMs, outerSignal) {
+    const controller = new AbortController();
+    const onOuterAbort = () => {
+        controller.abort(outerSignal.reason);
+    };
+    if (outerSignal.aborted)
+        controller.abort(outerSignal.reason);
+    else
+        outerSignal.addEventListener("abort", onOuterAbort, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new Error(`Deadline of ${String(timeoutMs)}ms expired`));
+    }, timeoutMs);
+    try {
+        return { ok: true, value: await work(controller.signal) };
+    }
+    catch (error) {
+        // Der Abbruch des AUFRUFERS ist kein Fristablauf — er ist ein Abbruch.
+        return { ok: false, timedOut: timedOut && !outerSignal.aborted, error };
+    }
+    finally {
+        clearTimeout(timer);
+        outerSignal.removeEventListener("abort", onOuterAbort);
+    }
+}
+//# sourceMappingURL=deadline.js.map

package/dist/cli/deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../../src/cli/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAyC,EACzC,SAAiB,EACjB,WAAwB;IAExB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,YAAY,GAAG,GAAS,EAAE;QAC9B,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC,CAAC;IACF,IAAI,WAAW,CAAC,OAAO;QAAE,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;;QACzD,WAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzE,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,QAAQ,GAAG,IAAI,CAAC;QAChB,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,eAAe,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5E,CAAC,EAAE,SAAS,CAAC,CAAC;IAEd,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,uEAAuE;QACvE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;IAC1E,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,WAAW,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}