@lorepack/cli 0.0.0-stage → 0.1.0-alpha.0

package/dist/framework/program.js

@@ -0,0 +1,189 @@
+import { EXIT_CODES, LoreError, renderAsJson, renderForCli } from '@lorepack/core';
+import { Command, CommanderError } from 'commander';
+import { registerCommands } from '../commands/index.js';
+import { createContext, resolveGlobalOptions, } from './context.js';
+import { exitAfterFlush } from './exit.js';
+import { validateCommandMetadata } from './metadata.js';
+export const CLI_NAME = 'lorepack';
+function defaultStreams() {
+    return {
+        stdout: process.stdout,
+        stderr: process.stderr,
+        isTty: process.stdout.isTTY === true,
+        errorIsTty: process.stderr.isTTY === true,
+        columns: process.stdout.columns ?? process.stderr.columns,
+    };
+}
+export function buildProgram(definitions, options, hooks) {
+    validateCommandMetadata(definitions);
+    const streams = options.streams ?? defaultStreams();
+    const program = new Command()
+        .name(CLI_NAME)
+        .description('Build, version, and deploy the context your AI depends on.')
+        .version(options.version ?? '0.0.0', '-v, --version')
+        .option('--json', 'emit machine-readable output on stdout', false)
+        .option('--verbose', 'include stage detail and debug diagnostics', false)
+        .option('--no-color', 'disable colour')
+        .option('--cwd <path>', 'run against a project in another directory')
+        .showSuggestionAfterError(true)
+        .exitOverride();
+    program.configureOutput({
+        writeOut: (text) => streams.stdout.write(text),
+        writeErr: (text) => streams.stderr.write(text),
+        // Commander writes its own error before throwing, which would print the message twice
+        // once the central handler renders it. Suppress the first: the thrown CommanderError
+        // carries the same text, and one renderer owns how a failure looks.
+        outputError: () => { },
+    });
+    for (const definition of definitions) {
+        const command = program.command(definition.name).description(definition.description);
+        for (const alias of definition.aliases ?? [])
+            command.alias(alias);
+        for (const argument of definition.arguments ?? []) {
+            command.argument(argument.required === false ? `[${argument.name}]` : `<${argument.name}>`, argument.description);
+        }
+        for (const flag of definition.flags ?? []) {
+            command.option(flag.flags, flag.description, flag.defaultValue);
+        }
+        command.exitOverride();
+        command.action(async (...actionArguments) => {
+            // commander passes positional arguments, then the options object, then the command.
+            const commandInstance = actionArguments.at(-1);
+            const flags = actionArguments.at(-2);
+            const positional = actionArguments
+                .slice(0, -2)
+                .filter((value) => typeof value === 'string');
+            const globalOptions = resolveGlobalOptions({ ...program.opts(), ...flags }, options.env ?? process.env, streams.isTty, streams.errorIsTty ?? streams.isTty);
+            const context = createContext(globalOptions, streams, options.signal);
+            hooks.onContext(context);
+            const result = await definition.handler(positional, { ...flags, _command: commandInstance }, context);
+            hooks.onResult(result, context);
+        });
+    }
+    return program;
+}
+/**
+ * Runs the CLI and returns the exit code.
+ *
+ * Every failure funnels through here: a `LoreError` renders with its remediation and maps
+ * to its documented exit code, and anything unexpected becomes `LORE_E_INTERNAL`. No
+ * command decides how an error looks or what it exits with.
+ */
+export async function runCli(argv, options = {}) {
+    const streams = options.streams ?? defaultStreams();
+    const exitProcess = options.exitProcess ?? true;
+    let code = 0;
+    // One interrupt asks the current command to stop at its next checkpoint, which is what
+    // lets a build discard its candidate and leave the active pointer alone. A second one
+    // means the user is no longer asking, so the process ends immediately.
+    const controller = new AbortController();
+    const signal = options.signal ?? controller.signal;
+    const interrupt = () => {
+        if (controller.signal.aborted) {
+            // Still through the flush: the message explaining why the process is ending is the
+            // one most likely to be lost, because nothing follows it to push the pipe along.
+            void exitAfterFlush(EXIT_CODES.USER, streams);
+            return;
+        }
+        controller.abort();
+        streams.stderr.write('\nInterrupted. Finishing the current step and rolling back.\n');
+    };
+    const installHandlers = exitProcess && options.signal === undefined;
+    if (installHandlers) {
+        process.on('SIGINT', interrupt);
+        process.on('SIGTERM', interrupt);
+    }
+    // A holder rather than a plain `let`: the assignment happens inside a callback, and
+    // control-flow analysis would otherwise narrow the variable to null at the catch site.
+    const state = { context: null };
+    const program = buildProgram(options.commands ?? registerCommands(), { ...options, streams, signal }, {
+        onContext: (context) => {
+            state.context = context;
+        },
+        onResult: (result, context) => {
+            if (result === undefined)
+                return;
+            if (context.options.json) {
+                if (result.json !== undefined)
+                    streams.stdout.write(`${JSON.stringify(result.json, null, 2)}\n`);
+            }
+            else if (result.human !== undefined && result.human !== '') {
+                streams.stdout.write(result.human.endsWith('\n') ? result.human : `${result.human}\n`);
+            }
+            if (result.exitCode !== undefined)
+                code = result.exitCode;
+        },
+    });
+    try {
+        await program.parseAsync([...argv]);
+    }
+    catch (error) {
+        // A parse failure happens before any context exists, so fall back to scanning argv:
+        // a user who asked for --json should get JSON even when the argument itself was wrong.
+        const jsonRequested = state.context?.options.json === true || argv.includes('--json');
+        code = handleFailure(error, streams, state.context, jsonRequested);
+    }
+    if (installHandlers) {
+        process.off('SIGINT', interrupt);
+        process.off('SIGTERM', interrupt);
+    }
+    if (exitProcess)
+        await exitAfterFlush(code, streams);
+    return code;
+}
+function handleFailure(error, streams, context, jsonRequested) {
+    // commander throws for --help and --version, which are successful outcomes.
+    if (error instanceof CommanderError) {
+        if (error.code === 'commander.helpDisplayed' || error.code === 'commander.version')
+            return 0;
+        if (error.code === 'commander.help')
+            return 0;
+        // Every argument-shaped failure becomes a typed error, so a user sees one format and
+        // a script sees one exit code. `excessArguments` is what commander reports for an
+        // unknown command when no subcommands are registered yet.
+        const argumentCodes = new Set([
+            'commander.unknownCommand',
+            'commander.unknownOption',
+            'commander.excessArguments',
+            'commander.missingArgument',
+            'commander.invalidArgument',
+            'commander.missingMandatoryOptionValue',
+            'commander.optionMissingArgument',
+        ]);
+        if (argumentCodes.has(error.code)) {
+            const wrapped = new LoreError('LORE_E_INVALID_ARGUMENT', error.message.replace(/^error:\s*/i, '').trim(), { remediation: `Run \`${CLI_NAME} --help\` to see available commands and options.` });
+            if (jsonRequested) {
+                streams.stdout.write(`${JSON.stringify(renderAsJson(wrapped), null, 2)}\n`);
+            }
+            else {
+                streams.stderr.write(`${renderForCli(wrapped, { color: errorColor(context, streams) })}\n`);
+            }
+            return EXIT_CODES.USER;
+        }
+        streams.stderr.write(error.message.endsWith('\n') ? error.message : `${error.message}\n`);
+        return error.exitCode === 0 ? EXIT_CODES.USER : error.exitCode;
+    }
+    const loreError = LoreError.from(error);
+    if (jsonRequested) {
+        streams.stdout.write(`${JSON.stringify(renderAsJson(loreError), null, 2)}\n`);
+    }
+    else {
+        streams.stderr.write(`${renderForCli(loreError, {
+            verbose: context?.options.verbose === true,
+            color: errorColor(context, streams),
+        })}\n`);
+    }
+    return loreError.exitCode;
+}
+/**
+ * Colour for an error.
+ *
+ * A failure can happen before the context exists, which is exactly when the message matters
+ * most, so this falls back to the stream rather than giving up on the question.
+ */
+function errorColor(context, streams) {
+    if (context != null)
+        return context.options.colorStderr;
+    return (streams.errorIsTty ?? streams.isTty) && process.env.NO_COLOR === undefined;
+}
+//# sourceMappingURL=program.js.map

package/dist/framework/program.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { registerCommands } from './commands/index.js';
+export { initCommand } from './commands/init.js';
+export { type CommandContext, createContext, type GlobalOptions, resolveGlobalOptions, type Streams, } from './framework/context.js';
+export { type CommandArgumentDefinition, type CommandExample, type CommandFlagDefinition, type CommandMetadata, type CompletionContext, type CompletionProvider, type CompletionValueKind, validateCommandMetadata, } from './framework/metadata.js';
+export { buildProgram, CLI_NAME, type CommandDefinition, type CommandHandler, type CommandResult, type RunOptions, runCli, } from './framework/program.js';
+export { enclosingProject, findSecretShaped, type InitOptions, type InitPlan, type InitResult, planInit, projectNameFrom, renderConfig, renderIgnore, runInit, } from './services/init.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EACL,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,aAAa,EAClB,oBAAoB,EACpB,KAAK,OAAO,GACb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,MAAM,GACP,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,OAAO,GACR,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { registerCommands } from './commands/index.js';
+export { initCommand } from './commands/init.js';
+export { createContext, resolveGlobalOptions, } from './framework/context.js';
+export { validateCommandMetadata, } from './framework/metadata.js';
+export { buildProgram, CLI_NAME, runCli, } from './framework/program.js';
+export { enclosingProject, findSecretShaped, planInit, projectNameFrom, renderConfig, renderIgnore, runInit, } from './services/init.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAEL,aAAa,EAEb,oBAAoB,GAErB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAQL,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,YAAY,EACZ,QAAQ,EAKR,MAAM,GACP,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAIhB,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,OAAO,GACR,MAAM,oBAAoB,CAAC"}

package/dist/migrations/README.md

@@ -0,0 +1,7 @@
+# migrations
+
+Raw SQL migrations, applied by `runMigrations` in this package. No ORM: versioned SQL is inspectable, and the same statements are the basis of the D1 projection in a later phase.
+
+`state/` creates the mutable project database under `.lore/`. `build/` creates the catalog inside a sealed build. They are separate sets on purpose: running both into one database would put empty `builds` and `active_build` tables inside every build, which is the confusion between operational state and canonical content that invariant 1 exists to prevent.
+
+They live inside this package, and `files` in its package.json publishes them, because an asset the code reads has to travel with the code. They used to sit at the repository root, where every test found them and no install did (#164).

package/dist/migrations/build/0001_catalog.sql

@@ -0,0 +1,85 @@
+-- The catalog inside a sealed build. Written once by the compiler, then opened read-only
+-- forever. Schema semantics stay close to D1 so the Cloudflare projection is a
+-- translation rather than a redesign (architecture section 17.4).
+
+CREATE TABLE artifacts (
+  id             TEXT PRIMARY KEY,
+  source_id      TEXT NOT NULL,
+  relative_path  TEXT NOT NULL,
+  display_path   TEXT NOT NULL,
+  media_type     TEXT NOT NULL,
+  byte_size      INTEGER NOT NULL,
+  content_hash   TEXT NOT NULL,
+  parser_id      TEXT NOT NULL,
+  parser_version TEXT NOT NULL,
+  title          TEXT,
+  status         TEXT NOT NULL,
+  authority      INTEGER NOT NULL,
+  object_hash    TEXT NOT NULL,
+  metadata       TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE nodes (
+  id            TEXT PRIMARY KEY,
+  artifact_id   TEXT NOT NULL REFERENCES artifacts (id),
+  parent_id     TEXT REFERENCES nodes (id),
+  kind          TEXT NOT NULL,
+  ordinal       INTEGER NOT NULL,
+  title         TEXT,
+  text          TEXT,
+  heading_path  TEXT NOT NULL,
+  line_start    INTEGER,
+  line_end      INTEGER,
+  metadata      TEXT NOT NULL,
+  revision_hash TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE chunks (
+  id               TEXT PRIMARY KEY,
+  artifact_id      TEXT NOT NULL REFERENCES artifacts (id),
+  node_ids         TEXT NOT NULL,
+  heading_path     TEXT NOT NULL,
+  text             TEXT NOT NULL,
+  estimated_tokens INTEGER NOT NULL,
+  relative_path    TEXT NOT NULL,
+  line_start       INTEGER,
+  line_end         INTEGER,
+  revision_hash    TEXT NOT NULL
+) STRICT;
+
+-- Supersession is stored separately so an artifact can supersede several others without
+-- an encoded list, which keeps the rule resolution queryable.
+CREATE TABLE supersessions (
+  artifact_id    TEXT NOT NULL REFERENCES artifacts (id),
+  superseded_id  TEXT NOT NULL,
+  PRIMARY KEY (artifact_id, superseded_id)
+) STRICT;
+
+CREATE TABLE build_warnings (
+  id      INTEGER PRIMARY KEY,
+  code    TEXT NOT NULL,
+  class   TEXT NOT NULL,
+  path    TEXT,
+  message TEXT NOT NULL
+) STRICT;
+
+-- Column layout is fixed by architecture section 12.9. Ranking weights are applied at
+-- query time by the runtime and deliberately not stored here: baking them into the index
+-- would make retuning ranking a rebuild.
+CREATE VIRTUAL TABLE chunks_fts USING fts5 (
+  chunk_id UNINDEXED,
+  artifact_id UNINDEXED,
+  status UNINDEXED,
+  authority UNINDEXED,
+  path,
+  title,
+  heading,
+  body,
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+
+CREATE INDEX nodes_artifact ON nodes (artifact_id);
+CREATE INDEX nodes_parent ON nodes (parent_id);
+CREATE INDEX chunks_artifact ON chunks (artifact_id);
+CREATE INDEX artifacts_status ON artifacts (status);
+CREATE INDEX artifacts_path ON artifacts (relative_path);

package/dist/migrations/build/0002_tables.sql

@@ -0,0 +1,43 @@
+-- The typed-table catalog (architecture section 8.4).
+--
+-- Physical tables are created at import time with generated names, so they cannot appear
+-- here. What can, and does, is the mapping from a stable Lore table id to the physical name,
+-- which is the only place the two are connected. Nothing else in the system is allowed to
+-- take a SQL identifier from user content.
+
+CREATE TABLE tables (
+  id            TEXT PRIMARY KEY,
+  artifact_id   TEXT NOT NULL REFERENCES artifacts (id),
+  name          TEXT NOT NULL,
+  sheet         TEXT,
+  -- The generated physical table, validated against a strict identifier pattern before it
+  -- is ever interpolated into DDL or a query.
+  sql_name      TEXT NOT NULL UNIQUE,
+  row_count     INTEGER NOT NULL,
+  relative_path TEXT NOT NULL,
+  line_start    INTEGER,
+  line_end      INTEGER,
+  metadata      TEXT NOT NULL
+) STRICT;
+
+-- Ordinal is stored rather than implied by rowid: `describeTable` must return columns in the
+-- order the source declared them, and a query plan is free to return rows in any order.
+CREATE TABLE table_columns (
+  table_id          TEXT NOT NULL REFERENCES tables (id),
+  ordinal           INTEGER NOT NULL,
+  name              TEXT NOT NULL,
+  sql_name          TEXT NOT NULL,
+  type              TEXT NOT NULL,
+  nullable          INTEGER NOT NULL,
+  null_count        INTEGER NOT NULL,
+  distinct_estimate INTEGER NOT NULL,
+  distinct_is_exact INTEGER NOT NULL,
+  -- Stored as text regardless of the column's type. A STRICT table needs one storage class
+  -- per column, and these hold numbers, dates and strings depending on the row. They are
+  -- reported, never compared, so text is the honest choice.
+  min_value         TEXT,
+  max_value         TEXT,
+  PRIMARY KEY (table_id, ordinal)
+) STRICT;
+
+CREATE INDEX tables_artifact ON tables (artifact_id);

package/dist/migrations/build/0003_table-cell-range.sql

@@ -0,0 +1,13 @@
+-- The cell range a table was read from (#235).
+--
+-- `tables` already stores the rest of the locator as columns: relative_path, sheet,
+-- line_start, line_end. The cell range was the one part left out, so it survived only inside
+-- the parser-defined `metadata` blob and `describeTable` returned a locator naming a file
+-- rather than a range. Architecture section 10.8 is explicit that a queried row traces back to
+-- a sheet and a cell range, so this belongs beside the other locator parts rather than behind
+-- a key one parser happens to write.
+--
+-- Nullable, because most tables have no such thing. A CSV file is one table with no cell
+-- range, and reporting an invented one would be worse than reporting none.
+
+ALTER TABLE tables ADD COLUMN cell_range TEXT;

package/dist/migrations/build/0004_chunk-page.sql

@@ -0,0 +1,11 @@
+-- The page a chunk is on (#241).
+--
+-- `nodes` could already carry a page inside its `metadata` blob, and the PDF parser wrote one
+-- there. `chunks` could not, and search hits, context items and export citations are all built
+-- from chunks. So the page reached the node table and stopped, and every citation of a PDF
+-- named the file and then a line number of 1, which is not where the text is.
+--
+-- Nullable, because most formats have no such thing. A Markdown chunk has a line range and no
+-- page, and inventing either is what this column exists to stop.
+
+ALTER TABLE chunks ADD COLUMN page INTEGER;

package/dist/migrations/state/0001_state.sql

@@ -0,0 +1,40 @@
+-- Mutable project state. Never part of a build: sealed build databases are read-only,
+-- and everything here is operational rather than canonical (architecture section 11.1).
+
+CREATE TABLE builds (
+  build_id   TEXT PRIMARY KEY,
+  state      TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  artifacts  INTEGER NOT NULL DEFAULT 0,
+  nodes      INTEGER NOT NULL DEFAULT 0,
+  chunks     INTEGER NOT NULL DEFAULT 0,
+  tables_    INTEGER NOT NULL DEFAULT 0,
+  table_rows INTEGER NOT NULL DEFAULT 0
+) STRICT;
+
+-- Exactly one row, enforced by the primary key check. The generation is monotonic and
+-- never repeats, including after a rollback, so a reader can detect a change by comparing
+-- a single integer.
+CREATE TABLE active_build (
+  id             INTEGER PRIMARY KEY CHECK (id = 1),
+  build_id       TEXT REFERENCES builds (build_id),
+  generation     INTEGER NOT NULL DEFAULT 0,
+  activated_at   TEXT
+) STRICT;
+
+INSERT INTO active_build (id, build_id, generation, activated_at) VALUES (1, NULL, 0, NULL);
+
+-- Wall-clock and machine facts, deliberately outside the build so two machines can agree
+-- on a build id while disagreeing about how long it took (architecture section 11.7).
+CREATE TABLE build_receipts (
+  build_id          TEXT PRIMARY KEY REFERENCES builds (build_id),
+  started_at        TEXT NOT NULL,
+  completed_at      TEXT NOT NULL,
+  duration_ms       INTEGER NOT NULL,
+  reused_artifacts  INTEGER NOT NULL,
+  rebuilt_artifacts INTEGER NOT NULL,
+  platform          TEXT NOT NULL,
+  node_version      TEXT NOT NULL
+) STRICT;
+
+CREATE INDEX builds_created_at ON builds (created_at DESC);