@bitcobblers/wod-wiki-tools 0.0.0-stage → 0.36.2134

package/dist/index.d.cts

@@ -0,0 +1,356 @@
+import { WodWikiIRFile, StatementNode, ExecutionLog, LanguagePack } from '@bitcobblers/wod-wiki-engine';
+import { INowProvider, IEffort } from '@bitcobblers/wod-wiki-lang';
+import { QueryServiceStores, QueryResult, RowsQueryResult, FindQueryResult, PipelineResult } from '@bitcobblers/wod-wiki-wql';
+import { EventRecord, AnalyticsDataPoint, Session, Note, BlockIndexRow, BlockRevision } from '@bitcobblers/wod-wiki-core';
+import { IStorage } from '@bitcobblers/wod-wiki-storage';
+import { Database } from '@bitcobblers/wod-wiki-storage/sql';
+
+/**
+ * Headless Parse Command Runner
+ *
+ * Parses Whiteboard Script source text and emits a versioned IR parse-tree envelope.
+ */
+
+declare class ParseSyntaxError extends Error {
+    readonly errors: Array<{
+        message: string;
+        line?: number;
+    }>;
+    constructor(errors: Array<{
+        message: string;
+        line?: number;
+    }>, message?: string);
+}
+interface ParseOptions {
+    sport?: string;
+    sourceLabel?: string;
+}
+/**
+ * Parses Whiteboard Script source directly into a StatementNode IR envelope.
+ */
+declare function runParse(source: string, options?: ParseOptions): WodWikiIRFile<StatementNode>;
+
+/**
+ * Headless Execution Command Runner
+ *
+ * Executes Whiteboard Script through JIT compiler and runtime state machine,
+ * emitting a versioned execution-log IR envelope.
+ */
+
+interface RunOptions {
+    sport?: string;
+    dialect?: 'time' | 'log';
+    blockId?: string;
+    blockVersion?: number;
+    startTime?: number;
+    maxIterations?: number;
+    now?: INowProvider;
+    sourceLabel?: string;
+}
+/**
+ * Runs a workout script to completion using headless state machine and Node clock.
+ */
+declare function runExecution(source: string, options?: RunOptions): Promise<WodWikiIRFile<ExecutionLog>>;
+
+/**
+ * Headless WQL Query Command Runner
+ *
+ * Evaluates WQL queries against in-memory stores sourced from --corpus,
+ * --stdin-log, or --stdin-facts, and emits a versioned IR envelope.
+ */
+
+declare class WqlSyntaxError extends Error {
+    readonly query: string;
+    readonly syntaxError: string;
+    constructor(query: string, syntaxError: string);
+}
+interface QueryCliOptions {
+    corpusPath?: string;
+    stdinLog?: string;
+    stdinFacts?: string;
+    preferredUnit?: string;
+    sourceLabel?: string;
+    /** Pre-built store bundle (e.g. sqlite-backed). When set, the corpus/stdin
+     *  dataset options are ignored. */
+    stores?: QueryServiceStores;
+}
+interface LoadedData {
+    eventRecords: EventRecord[];
+    facts: AnalyticsDataPoint[];
+    results: Session[];
+    notes: Note[];
+    blocks: BlockIndexRow[];
+    revisions: BlockRevision[];
+    efforts: IEffort[];
+    noteTags: Record<string, string[]>;
+}
+declare function loadQueryData(options: QueryCliOptions): LoadedData;
+/**
+ * Runs a WQL query against the provided in-memory dataset and returns a versioned IR envelope.
+ */
+declare function runQueryCli(wqlString: string, options?: QueryCliOptions): Promise<WodWikiIRFile<QueryResult | RowsQueryResult | FindQueryResult | PipelineResult>>;
+
+/**
+ * Dynamic Language Pack Loader
+ *
+ * Dynamically loads and registers Language Packs passed via `--pack <module-spec>`.
+ * Throws PackLoadError on failure, enabling exit code 3 handling.
+ */
+
+declare class PackLoadError extends Error {
+    readonly spec: string;
+    readonly originalError: unknown;
+    constructor(spec: string, originalError: unknown);
+}
+/**
+ * Dynamically imports a Language Pack module and registers it.
+ *
+ * @param moduleSpec - Relative or absolute path, or package name.
+ */
+declare function loadLanguagePack(moduleSpec: string): Promise<LanguagePack>;
+
+/**
+ * CLI Output Formatters (JSON, ASCII Table, CSV)
+ *
+ * Implements presentation formatting for parse-tree, execution-log,
+ * and WQL query results across json, table, and csv formats.
+ */
+
+type OutputFormat = 'json' | 'table' | 'csv';
+/**
+ * Format StatementNode parse tree
+ */
+declare function formatParseOutput(ir: WodWikiIRFile<StatementNode>, format: OutputFormat, pretty?: boolean): string;
+/**
+ * Format ExecutionLog runtime output
+ */
+declare function formatExecutionOutput(ir: WodWikiIRFile<ExecutionLog>, format: OutputFormat, pretty?: boolean): string;
+/**
+ * Format QueryResult / RowsQueryResult / FindQueryResult / PipelineResult
+ */
+declare function formatQueryOutput(ir: WodWikiIRFile<QueryResult | RowsQueryResult | FindQueryResult | PipelineResult>, format: OutputFormat, pretty?: boolean): string;
+
+/**
+ * Unified `wod` CLI Runner
+ *
+ * Implements CLI command routing, argument parsing, pipe handling,
+ * and exit code conventions per wayfinder #962 and issue #967.
+ *
+ * Exit Codes:
+ *   0 - OK / Success (including empty query results)
+ *   1 - Runtime error (file missing, bad arguments, execution error)
+ *   2 - Parse / Syntax error (invalid Whiteboard Script or malformed WQL)
+ *   3 - Pack load error (failed to import or register --pack)
+ */
+
+interface CliParsedArgs {
+    subcommand?: 'parse' | 'run' | 'query' | 'download' | 'import' | 'build' | 'seed' | 'reset' | 'init' | 'server' | 'serve' | 'playground' | 'help' | 'version';
+    target?: string;
+    /** Second positional: the id (download) or file (import) after the kind. */
+    target2?: string;
+    corpus?: string;
+    stdinLog?: boolean;
+    stdinFacts?: boolean;
+    format: OutputFormat;
+    output?: string;
+    packs: string[];
+    sport?: string;
+    unit?: string;
+    help?: boolean;
+    version?: boolean;
+    /** SQLite database path (--db). Defaults to WOD_WIKI_DB or ./wodwiki.db. */
+    db?: string;
+    /** Backend driver override (--db-driver): sqlite | postgres | turso. */
+    dbDriver?: string;
+    /** PostgreSQL connection URL (--database-url) or component flags below. */
+    databaseUrl?: string;
+    postgresHost?: string;
+    postgresPort?: string;
+    postgresUser?: string;
+    postgresPassword?: string;
+    postgresDatabase?: string;
+    postgresSsl?: string;
+    /** Turso/libSQL target (--turso-url) plus its auth token. */
+    tursoUrl?: string;
+    tursoAuthToken?: string;
+    /** Explicit environment file (--env-file); a missing file is an error. */
+    envFile?: string;
+    /** Hosting bind address/port and prebuilt frontend directory (server/playground). */
+    host?: string;
+    port?: string;
+    dist?: string;
+    /** IR debug output: undefined = off, '' = default file name, otherwise the file name. */
+    debug?: string;
+    /** Extra seed source directories for `wod seed` (repeatable). */
+    sources: string[];
+    /** `wod build`: scaffold markdown stubs for newly discovered efforts. */
+    scaffold?: boolean;
+    /** `wod build`: extra template markdown file compiled as the `template` chunk. */
+    template?: string;
+    /** `wod build`: content repo root (alias for the positional directory). */
+    dir?: string;
+}
+declare function parseCliArgs(args: string[]): CliParsedArgs;
+declare function readStdin(): Promise<string>;
+/**
+ * Main CLI entry point. Returns numeric exit code.
+ */
+declare function cliMain(argv?: string[], io?: {
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+    readStdinFn?: () => Promise<string>;
+}): Promise<number>;
+
+/**
+ * Database configuration for the `wod` CLI (and the dev server): explicit
+ * per-property flags → process env → .env file (native node:util.parseEnv,
+ * non-mutating).
+ *
+ * Precedence: flags beat env beats .env. `--db` selects local SQLite even
+ * when env configures a remote backend; explicit `--db-driver` /
+ * `--postgres-*` / `--turso-*` flags select that backend. Conflicting
+ * explicit selectors and ambiguous env backends are rejected. Labels and
+ * error messages never contain credentials.
+ */
+/** Optional per-property flag bag — every property unset unless given. */
+interface CliDatabaseOptions {
+    /** --db: explicit SQLite file. Selects sqlite even when env has a remote backend. */
+    db?: string;
+    /** --db-driver: sqlite | postgres | turso. */
+    dbDriver?: string;
+    /** --database-url: driver-scoped URL (mirrors DATABASE_URL). */
+    databaseUrl?: string;
+    postgresHost?: string;
+    postgresPort?: string;
+    postgresUser?: string;
+    postgresPassword?: string;
+    postgresDatabase?: string;
+    /** --postgres-ssl <mode>: true/false or disable | prefer | require | verify-ca | verify-full. */
+    postgresSsl?: string | boolean;
+    tursoUrl?: string;
+    tursoAuthToken?: string;
+    /** --env-file: explicit file is mandatory — a missing file is an error. */
+    envFile?: string;
+}
+/** Discriminated backend selection. `label` is credential-free and safe to
+ * print on every variant. sqlite is pure-local (absolute `path`); every
+ * remote libsql target normalizes to turso. */
+type PostgresSslMode = 'disable' | 'prefer' | 'require' | 'verify-ca' | 'verify-full';
+type CliDatabaseConfig = {
+    kind: 'sqlite';
+    label: string;
+    path: string;
+} | {
+    kind: 'postgres';
+    label: string;
+    url: string;
+    host: string;
+    port: number;
+    database: string;
+    user?: string;
+    password?: string;
+    ssl: PostgresSslMode;
+} | {
+    kind: 'turso';
+    label: string;
+    url: string;
+    authToken?: string;
+};
+/**
+ * Load a NON-MUTATING env object from the dotenv tier ONLY: an explicit
+ * --env-file is mandatory when given (missing file → error); otherwise
+ * `.env` in the working directory, falling back to the nearest ancestor
+ * (workspace root) `.env`. Callers merge over process.env themselves
+ * ({ ...loadCliEnvironment(file), ...process.env }); process.env is never
+ * written.
+ */
+declare function loadCliEnvironment(envFile?: string): Record<string, string | undefined>;
+/**
+ * Resolve the effective database configuration: flags > env > .env. Pass
+ * `env` to supply an already-merged tier (nothing is re-read); without it
+ * the .env tier (loadCliEnvironment) sits under the true process tier.
+ * Kind-pinning flags (--db, --db-driver, --turso-url/--turso-auth-token,
+ * --postgres-*) override even a malformed env driver; conflicting pins and
+ * ambiguous env backends are rejected. Never echoes credentials.
+ */
+declare function resolveDatabaseConfig(options?: CliDatabaseOptions, env?: Record<string, string | undefined>): CliDatabaseConfig;
+
+/**
+ * Local SQLite seam for the `wod` CLI.
+ *
+ * Opens a libsql `file:` database, initializes the shared storage schema
+ * (KV store tables + domain projections), and adapts the rows into the WQL
+ * store interfaces — the same shape the playground builds over IndexedDB.
+ *
+ * Everything heavy is loaded lazily (`@libsql/client`,
+ * `@bitcobblers/wod-wiki-storage/sql`, node `fs`/`crypto`) so browser
+ * bundles that import the engine index never pull native drivers; the
+ * dynamic specifiers stay external in the CLI bundle.
+ */
+
+interface CliDb {
+    db: Database;
+    storage: IStorage;
+    /** Absolute path of the underlying .sqlite file — or the sanitized display
+     * label (URL without credentials) for remote backends. */
+    path: string;
+    close(): Promise<void>;
+}
+/**
+ * Open the CLI database: a legacy local sqlite path (internal callers,
+ * created/initialized as before) or a resolved backend config from ./config.
+ *
+ * opts.initialize (default true): run the schema + projection
+ * initialization. false → verify the schema/projection guards only: a
+ * missing local sqlite file is NOT created and yields an actionable
+ * `wod init` error; remote targets are only probed, never created.
+ *
+ * opts.create (explicit init requests only, postgres): when the configured
+ * PostgreSQL database is missing, openDatabase creates it through the admin
+ * "postgres" database before initializing. Turso has no management API —
+ * its hosted target must already exist.
+ */
+declare function openCliDb(target?: string | CliDatabaseConfig, opts?: {
+    initialize?: boolean;
+    create?: boolean;
+}): Promise<CliDb>;
+
+/**
+ * server.ts — `wod server` (alias `serve`) / `wod playground` (Bun-only front
+ * door).
+ *
+ * Serves the packaged engine stack: the shared fetch handler shipped in this
+ * package (the same code the Docker image serves) plus the frontend build
+ * packaged under the engine's dist/web/ — no repository checkout, no runtime
+ * build.
+ *
+ * server      probes the configured database first (never creates schema —
+ *             that's `wod init`), then serves API + SPA.
+ * playground  serves the browser-storage SPA build and never opens a database
+ *             (every /api request answers 404).
+ *
+ * Retains the event loop until SIGINT/SIGTERM; shutdown drains in-flight
+ * requests before closing the database.
+ */
+
+type WriteOut = (text: string) => void;
+type CliServerMode = 'server' | 'playground';
+interface CliServerOptions {
+    /** Resolved database configuration. REQUIRED for 'server'; ignored — never
+     * opened or validated — for 'playground'. */
+    database?: CliDatabaseConfig;
+    host?: string;
+    port?: string;
+    /** Explicit dist directory (flag or PLAYGROUND_DIST); must already exist. */
+    dist?: string;
+    /** Merged CLI environment (process env + .env). */
+    env: Record<string, string | undefined>;
+}
+/**
+ * Start the shared server for `wod server` / `wod playground`. Throws on any
+ * startup failure; on success it never returns until SIGINT/SIGTERM (drain,
+ * close database, exit 0).
+ */
+declare function runCliServer(mode: CliServerMode, options: CliServerOptions, writeOut: WriteOut): Promise<void>;
+
+export { type CliDatabaseConfig, type CliDb, type CliParsedArgs, type CliServerMode, type CliServerOptions, type OutputFormat, PackLoadError, type ParseOptions, ParseSyntaxError, type QueryCliOptions, type RunOptions, WqlSyntaxError, cliMain, formatExecutionOutput, formatParseOutput, formatQueryOutput, loadCliEnvironment, loadLanguagePack, loadQueryData, openCliDb, parseCliArgs, readStdin, resolveDatabaseConfig, runCliServer, runExecution, runParse, runQueryCli };