Feat: CLI + Service Mode

[jitsedesmet]

CLI + Service Mode (SPARQL 1.1): Implemented Scope

What was added

1) New shared package: @traqula/cli-utils

A dedicated package was added at packages/cli-utils to keep Node-specific CLI concerns out of @traqula/core.

It provides shared helpers for:

• argv parsing (parseCliArgs, getFlagAsString, getFlagAsBoolean, etc.)
• text/json input-output (readTextInput, writeTextOutput, readJsonInput, writeJsonOutput)
• JSONL service orchestration (runJsonlService)
• prefix map parsing (parsePrefixMappings)

---

2) New SPARQL 1.1 binaries

The following engine packages now expose CLI binaries via bin in their package.json files:

• @traqula/parser-sparql-1-1
  • binary: traqula-parser-sparql-1-1
• @traqula/generator-sparql-1-1
  • binary: traqula-generator-sparql-1-1
• @traqula/algebra-sparql-1-1
  • binary: traqula-algebra-sparql-1-1

Each package also includes bin build artifacts in files (for publish) and compiles bin/**/*.ts via updated engine tsconfigs.

---

3) Runtime reuse for service mode

Each engine now has a reusable CLI runtime module:

• parser: engines/parser-sparql-1-1/lib/cli.ts
• generator: engines/generator-sparql-1-1/lib/cli.ts
• algebra: engines/algebra-sparql-1-1/lib/cli.ts

These expose create...CliRuntime + handle...CliRequest, enabling long-lived service processes to reuse expensive parser/transformer instances across calls.

---

4) JSONL long-running service mode (stdio)

All three binaries support --service (JSONL over stdin/stdout), allowing external processes (including non-JS environments) to send requests and parse structured JSON responses.

Response envelope:

• success: { "id": ..., "ok": true, "result": ... }
• failure: { "id": ..., "ok": false, "error": { "message": "..." } }

---

5) CLI docs and tests

Updated READMEs:

• engines/parser-sparql-1-1/README.md
• engines/generator-sparql-1-1/README.md
• engines/algebra-sparql-1-1/README.md

Added focused runtime tests:

• engines/parser-sparql-1-1/test/cli.test.ts
• engines/generator-sparql-1-1/test/cli.test.ts
• engines/algebra-sparql-1-1/test/cli.test.ts

---

Monorepo/build wiring updates

• Added packages/cli-utils to root references:
  • tsconfig.json
  • tsconfig.cjs.json
• Added @traqula/cli-utils dependency to the three SPARQL 1.1 engine packages above.
• Added Node type support in engine tsconfigs where needed for bin code.
• Ensured dual-build compatibility (esm/cjs) for cli-utils.

---

Verification performed

• Type-check/build validated for affected packages (including bins).
• CLI smoke tests validated:
  • parser from stdin to AST JSON
  • parser -> generator roundtrip
  • parser -> algebra conversion
  • parser JSONL service with multiple requests
• Existing test suite run confirmed green (no regressions introduced), including new CLI tests.

---

Notes on design alignment

This implementation follows Traqula modularity:

• shared CLI concerns are centralized in a dedicated package (not duplicated per engine),
• engines keep language-specific transformation logic,
• long-running mode is process-safe and reuses expensive parser/transformer instances.