@loadmap/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Rojas
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @loadmap/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+npx @loadmap/cli check shop.loadmap          # exit 1 when an expect line fails; GitHub annotations under Actions
+npx @loadmap/cli record shop.loadmap --out shop.gif --caption
+npx @loadmap/cli record http://localhost:5173/ --out poster.png --poster
+```
+
+`loadmap check` compiles each `.loadmap` and tests its `expect` lines on the pessimistic edge (every capacity at its
+low bound). `loadmap record` draws a `.loadmap` (or opens a page that calls `expose()` from `@loadmap/export`) in
+headless Chromium and records it on a fixed clock: the same options give the same file. Recording needs Chromium
+once: `npx playwright install chromium`. `loadmap --help` lists every option.
+Docs: https://jaim3r0jas.github.io/loadmap/ · MIT

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { n as main } from "./src-B81_QU8o.js";
+// src/bin.ts
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});
+export {};

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/** A range of the source, as offsets: `from` inclusive, `to` exclusive. */
+interface Span {
+  from: number;
+  to: number;
+}
+interface Diagnostic extends Span {
+  severity: 'error' | 'warning';
+  message: string;
+  /** 1-based, like an editor shows them. */
+  line: number;
+  column: number;
+  /** A short suggestion shown under the mark: "did you mean "orders"?". */
+  hint?: string;
+}
+interface CheckOptions {
+  log?: (s: string) => void;
+  /** Where GITHUB_ACTIONS is read from: annotations are the default there. */
+  env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * `loadmap check`: compiles each definition and tests its expect lines. Resolves to the exit code: 1 when a
+ * definition has an error or an expectation fails, 2 for a usage mistake, 0 when everything holds.
+ */
+export declare function check(argv: string[], o?: CheckOptions): Promise<number>;
+/**
+ * A diagnostic as a GitHub Actions workflow command: an annotation on its line of the file in the pull request.
+ * https://docs.github.com/actions/reference/workflow-commands-for-github-actions
+ */
+export declare function github(d: Diagnostic, file: string, source: string): string;
+export declare const USAGE = "loadmap check <file.loadmap>… [--format text|github]\nloadmap record <url | file.loadmap> --out <file.gif|.webm|.mp4|.png|.svg> [options]\n\ncheck compiles each definition and tests its expect lines on the pessimistic edge (every capacity at its low\nbound). It exits 1 when a definition has an error or an expectation fails, 0 when everything holds.\n\n  --format <f>          text, or github to add annotations on the lines (the default under GitHub Actions)\n\nrecord opens the page in headless Chromium, finds the loadmap it exposes (expose() from @loadmap/export) and\nrecords it on a fixed clock, so the same options give the same file. A .loadmap file is drawn by the viewer that\ncomes with the command.\n\n  --out <file>          the extension picks the format: gif, webm, mp4, png or svg\n  --script <file.json>  [{ \"at\": 0, \"set\": { \"load\": 5 } }, { \"at\": 3, \"scenario\": \"Proposed\" }, …]\n                        or { \"seconds\", \"fps\", \"script\": […] }\n  --scenario <label>    start from a scenario's values (--set goes on top)\n  --set <key=value>     a value before recording starts; repeatable (--set load=30 --set pods=6)\n  --caption             the title, scenario and load above the board, the verdict below it\n  --story               play the definition's story, a step at a time (with --caption, its text below the board)\n  --poster              with .png: the board, the verdict, the limits and the scenarios compared\n  --seconds <n>         length of a video or GIF (default 8, or the script's)\n  --fps <n>             frames per second (default 30; GIF 15, at most 50)\n  --scale <n>           pixels per diagram unit (default 1, PNG 2)\n  --seed <n>            the sim's seed (default 1)\n  --name <name>         which exposed loadmap, when the page has several (default \"default\")\n  --width <px>          the browser window (default 1280; below 640 the diagram runs top to bottom)\n  --color-scheme <s>    light or dark, for a page that follows the system theme (default light)";
+export interface RecordArgs {
+  /** A page that calls expose(); empty with `file`. */
+  url: string;
+  /** A .loadmap definition to draw instead of a page. */
+  file?: string;
+  out: string;
+  script?: {
+    at: number;
+    scenario?: string;
+    set?: Record<string, string | number | boolean>;
+  }[];
+  scenario?: string;
+  set: Record<string, string | number | boolean>;
+  caption: boolean;
+  poster: boolean;
+  story: boolean;
+  seconds?: number;
+  fps?: number;
+  scale?: number;
+  seed?: number;
+  name: string;
+  width: number;
+  colorScheme: 'light' | 'dark';
+}
+/** Runs the command line; resolves to the exit code. */
+export declare function main(argv: string[], log?: (s: string) => void): Promise<number>;
+export declare function parseRecord(argv: string[]): Promise<RecordArgs>;
+/**
+ * Records in a fresh headless Chromium and returns the file's bytes. A .loadmap file is compiled here first (its
+ * errors are thrown, formatted), then drawn by the viewer in `o.viewer`: by default the one the build puts in
+ * dist/viewer.
+ */
+export declare function record(a: RecordArgs, o?: {
+  viewer?: string;
+}): Promise<Buffer>;
+export type { CheckOptions };

package/dist/index.js

@@ -0,0 +1 @@
+export { t as USAGE, a as check, o as github, n as main, r as parseRecord, i as record } from "./src-B81_QU8o.js";