ephemeris-cli 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# Ephemeris 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.
+Prepare numeric data, obtain a forecast, describe it deterministically, and plot the saved result through one Ephemeris interface. Node.js 22+; no Python, Gnomon installation, skill pack, browser, or plotting application required. PNG export uses the packaged @resvg/resvg-js renderer and bundled DejaVu Sans font; npm installs the platform dependency. SVG export remains pure JavaScript.
+
+Version 0.4.0 is maintained in the dedicated Ephemeris CLI repository. It is not published to npm. Tests and demonstrations use synthetic local services; no live forecasting quality is established.
+
+## Install and discover
+
+```bash
+# From this repository:
+npm install --global .
+ephemeris --help
+ephemeris forecast --help
+ephemeris forecast run --help
+ephemeris schema forecast
+
+# Alternatively, without installing:
+node bin/ephemeris.js --help
+```
+
+Every executable command has an offline operating guide: purpose, input semantics, examples, output meaning, effects, recovery, and interpretation limits. [The reference](docs/cli-reference.md) is generated from those same definitions. Help instructs agents to ask for missing units, business definitions, and assumptions, and to preserve unknowns rather than guess.
+
+## Inspect real data explicitly
+
+```bash
+ephemeris data inspect --input sales.csv \
+  --time-column date --value-column sales --frequency D \
+  --unit units --measurement period_total --timezone UTC \
+  --target-description 'Observed sales' --output inspected.json
+```
+
+Supported inputs: CSV/TSV with headers, JSON arrays of row objects, and JSONL. Choose columns explicitly. Optional `--series-column` groups independent series. Source order is retained. Inputs are bounded to 8 MiB and 100,000 rows.
+
+The snapshot includes selected history and original timestamp strings, source/content hashes, supplied metadata, coverage, frequency evidence, missing periods, duplicates, invalid/missing values, and zeros. Inspect `series[].report.ready_for_forecast`; inspection success alone does not establish readiness or model suitability. Nothing is sorted, filled, resampled, deduplicated, or repaired. Fix the original source explicitly and inspect again.
+
+Supported local time grids are whole-second subdaily, daily, weekly, and month-start. Unknown/unsupported calendars are reported as unverified. Datetimes must be ISO; date-only input remains date-only. Named-zone calendar forecasts may use sampling steps if reliable future dates cannot be projected. Explicit future timestamps can be supplied with raw request context and must continue the validated history grid. Missing timestamps mean unknown coverage/missing periods, not zero missing periods.
+
+Supplied units, timezone, target description, and measurement semantics are preserved. `period_total`, `period_average`, and `point_in_time` are distinct. Observed sales are not necessarily underlying demand. Zero observations do not establish stockouts, lost demand, or causal explanations.
+
+## Prepare, then submit
+
+```bash
+# No credentials, inference, or network access:
+ephemeris forecast run --input inspected.json \
+  --horizon 7 --quantiles 0.1,0.5,0.9 \
+  --dry-run --output prepared.json
+```
+
+For multi-series snapshots, choose `--series ID`. `--mode`, `--model`, `--horizon`, `--quantiles`, and `--context-len` override corresponding request fields. Snapshot mode defaults to route; raw API JSON requires mode. The API defaults horizon to 64 and context_len to 256. Horizon counts sampling steps, not necessarily calendar days. Use live `models list` for deployment-specific limits and capabilities.
+
+Set `EPHEMERIS_API_KEY` using your secret manager or environment. For an interactive Bash session:
+
+```bash
+read -rsp 'Ephemeris API key: ' EPHEMERIS_API_KEY
+export EPHEMERIS_API_KEY
+ephemeris auth status --verify
+ephemeris models list
+
+# This operation submits paid inference:
+ephemeris forecast run --input prepared.json \
+  --idempotency-key sales-run-001 --output forecast.json
+```
+
+Create a key in the [Ephemeris dashboard](https://ephemeris.cascade.industries/dashboard/api-keys). Keys are never accepted as CLI arguments or stored in artifacts. API credentials require HTTPS except on loopback development endpoints. `--base-url`/`EPHEMERIS_BASE_URL` chooses an origin, without `/api/v1`; redirects are not followed.
+
+Raw public API requests also work. They differ from raw Paracast:
+
+```json
+{
+  "mode": "route",
+  "series": [{"values": [100,101,99,103,104,102,105,107], "freq": "H"}],
+  "horizon": 24,
+  "quantiles": [0.1,0.5,0.9]
+}
+```
+
+Use `--input -` for stdin. `--context context.json` supplies local per-series timestamps, units, measurement semantics, identifiers, target descriptions, future-input roles, and scenario assumptions; it is never sent to the API. Narrative assumptions do not change the numeric forecast. See `forecast run --help` for the complete context contract. Frozen snapshots/prepared requests already fix their context and reject a second context file.
+
+The CLI deliberately rejects unknown request fields so local metadata cannot accidentally be sent to the service. Covariates are numeric API inputs: past channels align with history; future channels match horizon and require named past histories. `context.series[].future_covariate_roles` distinguishes `known_future`, `scenario_assumption`, and `unspecified`. Labels are caller assertions, not independently verified availability.
+
+## Reuse the saved artifact
+
+```bash
+ephemeris forecast describe --input forecast.json --output description.json
+ephemeris forecast plot --input forecast.json --output forecast.png
+# Scalable export, with every submitted observation visible:
+ephemeris forecast plot --input forecast.json --output forecast.svg --history all
+```
+
+Both commands are offline and deterministic. Missing labels do not require paid inference: copy the artifact to a new file, correct only caller-supplied local context metadata, keep the request/response unchanged, and rerun describe/plot. Timestamps still have to pass the grid checks; there is no separate annotation command. They do not run inference or change the saved artifact. For multi-series/multivariate results choose `--series-index` and `--variate-index` explicitly.
+
+The forecast artifact is versioned and contains the exact submitted request, complete submitted history, request hash, response, billing, request IDs, retry key, local context, and derived time axis. It discloses that service/model context caps may truncate the history actually used. Treat artifacts as data-bearing files. [Artifact contracts and Gnomon ownership](docs/contracts-and-ownership.md) describe the boundaries.
+
+Description reports saved billing amounts in millicredits and exact decimal credits: 1000 mc = 1 credit, so 100 mc is 0.1 credits. This is not a current balance check. Missing future inputs mean not supplied, not assumed zero or no future events. A forecast jump or constant-width band alone does not demonstrate forecast quality.
+
+Description names the last observed value as its comparison baseline and documents every calculation. Missing medians are not interpolated; horizon-wide aggregates remain null when incomplete. A sum of marginal medians is available only for declared period totals and is explicitly not a cumulative-distribution median or interval. Observed statistics use all submitted history.
+
+PNG and SVG plots include observed history, a forecast boundary, marginal median, and labeled quantile bands. Missing values break lines; crossed/missing bands are omitted and counted. Dates are used only when grounded in a supported grid; otherwise the x-axis is sampling steps. No external assets or scripts are embedded. The default view shows the most recent max(24, 2*horizon) observations, capped by available history, so long histories do not squeeze the forecast into a few pixels. The chart discloses shown/total counts; full history remains in the artifact. Use --history N or --history all to change only the view. --format png|svg can select output explicitly; filename extensions must match. With no extension or stdout, SVG remains the default; PNG stdout is binary and requires a pipe.
+
+Quantile bands do not establish calibrated coverage or accuracy. Marginal quantiles alone cannot provide cumulative-total uncertainty, path-dependent probabilities, or actual-peak distributions. Neither description nor plotting invents causes, confidence estimates, trading decisions, or inventory recommendations.
+
+## Recovery and persistence
+
+Every operation is explicit. Only `forecast run` submits inference. Model/account discovery reads the existing public API. There is no unsupported feedback endpoint, background scheduling, actual ingestion, or local tracking engine.
+
+A private `ephemeris.submission` v1 receipt is saved and synced to disk **before submission**, and its path and retry key are printed to stderr. For `--output forecast.json`, the default is `forecast.json.submission.json`; stdout submissions use `.ephemeris/submissions/<uuid>.json` in the current directory. `--receipt NEW_PATH` selects another path. A receipt write failure prevents the paid call. The receipt preserves the exact prepared request, full history/local context, origin, request hash, and key without credentials. Keep it private; it remains after success or failure and is never overwritten. Its `completion_unknown` status is not evidence that the server completed or even received the request. Archive/delete receipts explicitly when no longer needed. After a timeout/interruption, the outcome may be unknown. Use `--resume` to recover from the receipt even if you lose stderr or edit the original input. It reuses the original origin, request, and key; generating a fresh key can create a second paid forecast. The CLI never automatically retries. Server idempotency retention rules remain authoritative.
+
+```bash
+ephemeris forecast run --resume forecast.json.submission.json --output recovered.json
+# Offline inspection before recovery:
+ephemeris forecast run --resume forecast.json.submission.json --dry-run
+```
+
+Resume ignores EPHEMERIS_BASE_URL and rejects overrides of the origin, input, context, model, horizon, quantiles, or key. Only resume trusted receipts: the request hash detects edits, not forgery. Expired server idempotency records can result in a new charge; indefinite replay is not guaranteed.
+
+Output paths are reserved before paid submission; existing files are never overwritten. Files are created privately (`0600` where supported). If a paid result cannot be written, the CLI attempts to output the complete artifact on stdout and exits 8. Save stdout or retry the same request/key. A later malformed-response, description, or plotting error leaves the original artifact intact.
+
+Success output is JSON, or PNG/SVG for plotting. Diagnostics/errors are JSON Lines on stderr. `--output -` selects stdout. `--timeout` is 1–3600 seconds (default 300). Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Operation completed; inspection may still report not ready |
+| 2 | Invalid input/arguments/configuration or unusable saved shape |
+| 3 | Authentication/permission problem |
+| 4 | Insufficient credits |
+| 5 | Conflict/rate limit; inspect error and Retry-After |
+| 6 | Network, timeout, or service failure |
+| 7 | Other API/protocol failure |
+| 8 | Local file/output failure, including a broken output pipe |
+| 130 | Interrupted in-flight request |
+
+## Local demonstration and checks
+
+```bash
+# Uses synthetic observations and a local mock server; no live inference/charge.
+# Supply a NEW directory:
+npm run demo -- /tmp/ephemeris-demo
+
+npm test
+npm run docs:check
+npm run schemas:check
+npm run eval:smoke
+npm pack --dry-run
+```
+
+The demo writes CSV, inspection snapshot, prepared request, forecast artifact, description, SVG, PNG, and the durable submission receipt. `examples/daily-sales.csv` and `examples/hourly.json` contain synthetic demonstration data, not real customer history.
+
+Tests cover malformed files, missing data, DST/time alignment, multivariate shapes, context separation, numerical interpretation, SVG escaping/gaps, auth, retry recovery, and simulated disk-write failure. The [evaluation harness](evals/README.md) contains nine help-first scenarios. Its scripted adapter validates the harness and CLI, not unfamiliar-model usability. Actual agent trials and qualitative reviews are recorded separately under [evals/results](evals/results); see the [usability audit](docs/usability-audit.md). mechanical success does not establish that every explanation is correct or that the CLI works for every model. No live forecast-quality claim is made.
+
+Schemas work offline:
+
+```bash
+ephemeris schema forecast --kind request
+ephemeris schema forecast --kind prepared
+ephemeris schema forecast --kind artifact
+ephemeris schema forecast --kind data
+ephemeris schema forecast --kind submission
+```
+
+Developer drift checks against adjacent repositories:
+
+```bash
+npm run check:api -- /root/paracast-web/public/openapi-m1.json
+python3 scripts/gnomon-fixtures.py /root/Gnomon --check
+```
+
+Gnomon/Python is required only for regenerating/checking developer conformance fixtures, never for installed customer commands. Hosted Gnomon integration is a future option; an artifact import path does not currently exist. Historical evaluation, actual ingestion, and outcome review should use Gnomon in the next phase.
+
+## Release status
+
+0.3 adds durable submission receipts, receipt-based recovery, PNG export, readable recent-history views, actionable argument errors, and executable self-contained help examples. PNG adds a packaged renderer dependency.
+
+0.2 changed forecast output from raw API JSON to a versioned artifact; the response is at `/response`. `forecast --input ...` remains a compatibility spelling for `forecast run`. JSON schema/semantic versions are independent of the npm version.
+
+Publication and paid live inference are separate actions. Before publishing, settle package ownership/licensing, run actual agent acceptance trials, and make a separately authorized live API check. The generated reference is ready to host, but no website, package, or repository is published by CI.
+
+## Version diagnostics
+
+`ephemeris --version` prints the installed package version. `ephemeris version` (also `ephemeris version --json`) returns component, package version, nullable source build commit and supported local artifact schema versions. It works offline and never checks npm or the hosted service. Packed clean builds have a source commit; source checkouts or unverified builds report null. The hosted MCP's `get_version` reports its independent deployment version; it cannot inspect your local CLI or bridge.
+
+The CLI currently carries no open-source license grant (`UNLICENSED`); public npm availability does not itself grant one. Third-party asset licenses remain in assets/.

package/assets/DejaVu-LICENSE.txt

@@ -0,0 +1,78 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: DejaVu fonts
+Upstream-Author: Stepan Roh <src@users.sourceforge.net> (original author),
+                  see /usr/share/doc/fonts-dejavu-core/AUTHORS for full list
+Source: https://dejavu-fonts.github.io/
+
+Files: *
+Copyright: Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved.
+ Bitstream Vera is a trademark of Bitstream, Inc.
+ DejaVu changes are in public domain.
+License: bitstream-vera
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of the fonts accompanying this license ("Fonts") and associated
+ documentation files (the "Font Software"), to reproduce and distribute the
+ Font Software, including without limitation the rights to use, copy, merge,
+ publish, distribute, and/or sell copies of the Font Software, and to permit
+ persons to whom the Font Software is furnished to do so, subject to the
+ following conditions:
+ .
+ The above copyright and trademark notices and this permission notice shall
+ be included in all copies of one or more of the Font Software typefaces.
+ .
+ The Font Software may be modified, altered, or added to, and in particular
+ the designs of glyphs or characters in the Fonts may be modified and
+ additional glyphs or characters may be added to the Fonts, only if the fonts
+ are renamed to names not containing either the words "Bitstream" or the word
+ "Vera".
+ .
+ This License becomes null and void to the extent applicable to Fonts or Font
+ Software that has been modified and is distributed under the "Bitstream
+ Vera" names.
+ .
+ The Font Software may be sold as part of a larger software package but no
+ copy of one or more of the Font Software typefaces may be sold by itself.
+ .
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+ TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+ FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+ THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+ FONT SOFTWARE.
+ .
+ Except as contained in this notice, the names of Gnome, the Gnome
+ Foundation, and Bitstream Inc., shall not be used in advertising or
+ otherwise to promote the sale, use or other dealings in this Font Software
+ without prior written authorization from the Gnome Foundation or Bitstream
+ Inc., respectively. For further information, contact: fonts at gnome dot
+ org.
+
+Files: debian/*
+Copyright: (C) 2005-2006 Peter Cernak <pce@users.sourceforge.net>
+           (C) 2006-2011 Davide Viti <zinosat@tiscali.it>
+           (C) 2011-2013 Christian Perrier <bubulle@debian.org>
+           (C) 2013 Fabian Greffrath <fabian+debian@greffrath.com>
+License: GPL-2+
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later
+ version.
+ .
+ This program is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more
+ details.
+ .
+ You should have received a copy of the GNU General Public
+ License along with this package; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA  02110-1301 USA
+ .
+ On Debian systems, the full text of the GNU General Public
+ License version 2 can be found in the file
+ /usr/share/common-licenses/GPL-2'.

package/bin/ephemeris.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+// The awaited writer reports broken pipes as output failure (exit 8), including
+// paid-result recovery instructions. Do not turn a lost artifact into success.
+process.stdout.on('error', () => {});
+process.exitCode = await main(process.argv.slice(2));

package/build-info.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.4.0",
+  "commit": "5567777c156757427a664b7a5aad7685190247f3"
+}