@agentionai/fieldwork-cli 0.3.0 → 0.7.0

package/README.md

@@ -4,10 +4,10 @@
 
 ## Install
 
-Requires Node.js **22+** and npm. Version **0.3.0** is prepared for publication; until published, install the supplied archive:
+Requires Node.js **22+** and npm. Version **0.7.0** is prepared for publication; until published, install the supplied archive:
 
 ```sh
-npm install --global ./agentionai-fieldwork-cli-0.3.0.tgz
+npm install --global ./agentionai-fieldwork-cli-0.7.0.tgz
 fieldwork --version
 fieldwork --help
 ```
@@ -15,20 +15,23 @@ fieldwork --help
 After publication:
 
 ```sh
-npm install --global @agentionai/fieldwork-cli@0.3.0
+npm install --global @agentionai/fieldwork-cli@0.7.0
 ```
 
-A checkout and pnpm are not required to use the installed CLI. npm resolves Commander, its only runtime dependency. This package includes neither the server nor the web app and installs no services. Connect to a separately provisioned compatible API; this early API has no authentication, so use a trusted local/private deployment. Installing a new client does not update server behavior.
+Pin the version. The npm registry currently holds 0.3.0 and 0.4.0, which predate credentials and paged responses and cannot use the hosted service, so an unpinned install gets a client that fails against it.
+
+A checkout and pnpm are not required to use the installed CLI. npm resolves Commander, its only runtime dependency. This package includes neither the server nor the web app and installs no services. By default it connects to the hosted service at `https://app.fieldworkledger.com`, which requires a credential; a local server is named with `--url` or `FIELDWORK_URL`. Installing a new client does not update server behavior.
 
 ## Quick start
 
-Use actual server and campaign references; the example campaign must already exist:
+Issue an agent credential from the web app's Account page, then store it once for this machine. Use actual campaign references; the example campaign must already exist:
 
 ```sh
-fieldwork --url http://127.0.0.1:4310 campaigns list
+fieldwork auth login --token TOKEN
+fieldwork campaigns list
 mkdir memory-study
 cd memory-study
-fieldwork --url http://127.0.0.1:4310 setup campaign --campaign memory-study
+fieldwork setup campaign --campaign memory-study
 fieldwork context
 fieldwork experiments create --json '{"name":"Baseline","hypothesis":"The candidate meets the agreed target"}'
 fieldwork runs create --experiment baseline --json '{"title":"Attempt 1"}'
@@ -41,21 +44,26 @@ Creating a missing campaign is explicit: `setup campaign --campaign new-study --
 
 Run `fieldwork <group> <command> --help` for flags and payload requirements.
 
-| Command | Operations |
-| --- | --- |
-| `products` | list, get, create, update, delete |
-| `campaigns` | list, get, context, create, update, delete |
-| `experiments`, `runs` | list, get, context, create, update, delete |
-| `schemas` | list, publish, default, set-default, get, template, validate |
-| `charts` | fields, list, create, get, data, delete |
+| Command          | Operations                                                             |
+| ---------------- | ---------------------------------------------------------------------- |
+| `products`       | list, get, create, update, delete                                      |
+| `campaigns`      | list, get, context, create, update, delete                             |
+| `experiments`    | list, get, context, create, update, delete                             |
+| `runs`           | list, get, context, create, record, update, delete                     |
+| `artifacts`      | list, get, create, update, delete, diff                                |
+| `schemas`        | list, publish, default, set-default, get, template, validate, extend   |
+| `charts`         | fields, list, create, get, data, series, frontier, delete              |
 | `setup campaign` | Attach a directory to a campaign; optionally create a missing campaign |
-| `context` | Effective server, campaign scope, and live inherited context |
+| `context`        | Effective server, campaign scope, and live inherited context           |
+| `auth`           | login, status, logout: the credential stored for this server           |
+| `whoami`         | The credential's organization and current permissions                  |
+| `changelog`      | Recent releases of this CLI, offline                                   |
 
 - References accept stubs or UUIDs. Experiments/runs use campaign scope (`--campaign REF` or workspace); JSON `...Id` fields, schema versions, and charts require IDs.
 - Campaign list/create do not inherit product scope: pass `--product REF` when needed.
 - Schemas can belong to products, campaigns, or experiments. `schemas list --inherited` includes ancestors; defaults affect new records, not existing pins. Templates are illustrative, never measured evidence.
 - `schemas validate VERSION_ID --ready --json -` validates without saving. Invalid reports go to stdout, with `VALIDATION_FAILED` on stderr and exit 1; valid reports exit 0 even with missing-observation warnings. `--ready` checks required execution fields, not experiment variations.
-- Charts are immutable definitions over live typed successful-run data, with explicit exclusions and source run revisions. Discover fields before creation. No aggregation, expressions, or cross-version merging.
+- Charts are immutable definitions over live typed successful-run data, with explicit exclusions and source run revisions. Discover fields before creation. Optional typed aggregation supports mean/sample stdev with mean±SD whiskers or line bands; no arbitrary expressions or cross-version merging. Two choices about a raw chart are saved with it and can change: `charts series CHART_ID` colours it by a typed field or by groups of runs you define, and a scatter chart's `charts frontier CHART_ID --json '{"runIds":[...]}'` saves the runs to join, chosen rather than computed.
 - Create/update read an object with `--json JSON` or stdin using `--json -`. Data results are JSON on stdout; errors are JSON on stderr with nonzero status. Help/version are text and work offline.
 - Updates require the current `revision`. Campaign/experiment/run deletes require `--revision N`; product/chart deletes do not. Re-read on conflicts, never blindly retry a create or increment stale revisions.
 - Only planned runs can be deleted. Parents with child records are protected; experiments with schemas referenced by campaign charts are also protected. Deleting a chart does not delete runs.
@@ -63,7 +71,7 @@ Run `fieldwork <group> <command> --help` for flags and payload requirements.
 
 ## Workspaces, server selection, and agent skill
 
-Server precedence is `--url`, `FIELDWORK_URL`, legacy `LAB_URL`, nearest workspace config, then `http://127.0.0.1:4310`. Use an HTTP(S) origin without credentials, resource paths, queries, or fragments. Product scoping is not authentication.
+Server precedence is `--url`, `FIELDWORK_URL`, legacy `LAB_URL`, nearest workspace config, then `https://app.fieldworkledger.com`. A local server needs `--url http://127.0.0.1:4310` (or `FIELDWORK_URL`); a workspace set up against it remembers it. Credentials are stored per server, so a local token is never sent to the hosted service. Use an HTTP(S) origin without credentials, resource paths, queries, or fragments. Product scoping is not authentication.
 
 Setup creates `.fieldwork/workspace.json`, `README.md`, `fieldwork-skill.md`, an `AGENTS.md` reference (or appends to existing `agents.md`), and `docs/`, `assets/`, `logs/`, `results/`. Commands find the nearest binding upward from subdirectories. Setup refuses rebinding and preserves existing files. Legacy `.lab/workspace.json` remains supported. No files are uploaded or registered automatically.
 
@@ -77,3 +85,29 @@ npm root --global
 Compare and merge updates deliberately to preserve local instructions, or install the bundled file as `fieldwork/SKILL.md` in your agent's supported skill directory. The server's Docs page also provides copy/download, but reflects that server deployment's version.
 
 MCP, job orchestration, product queries/local search, managed Markdown recovery, artifact registration, and automatic per-run directory creation are not implemented. Local files and external URIs are data, not commands to execute; do not store secrets in records.
+
+### Schema extensions (0.4.0)
+
+`schemas extend VERSION_ID --json JSON [--dry-run]` accepts a complete proposed definition, creates a compatible immutable successor, and atomically advances matching experiment/run/default/chart pins. New optional fields and enum values are allowed; breaking validation or unit/direction/comparison changes are rejected. Old definitions and creation snapshots remain intact. Reload incremented revisions. Preview before applying; a stale source cannot be extended again. Requires the corresponding updated API. Included in CLI 0.4.0; the API must be updated separately.
+
+### Recipes and artifacts (0.4.0)
+
+`artifacts list --product REF`, `create --product REF --json`, `get/update/delete` with revision checks, and `diff FROM TO --product` are available in 0.4.0. Experiments and runs accept `artifacts: [stub-or-id]` references stored as immutable IDs; first reference permanently freezes the artifact, and changes require a `derivedFrom` successor with a new stub. Included in CLI 0.4.0; requires the updated API.
+
+### Selection, one-call recording and typed refs (0.5.0)
+
+`runs list` and `experiments list` accept `--where FIELD=VALUE` (also `!=`, `>=`, `<=`, `>`, `<`; repeatable, combined with AND), `--fields PATHS`, `--format tsv`, and `runs list --experiment REF`. They select and project recorded values and compute nothing. **They now exclude superseded records (`extras.superseded_by`) and work under abandoned experiments by default**; pass `--include-superseded` or `--include-abandoned` to see them. This part works against any compatible API.
+
+`runs record REF --json JSON` records observations and a status in one call, with the server reading the current revision, and `runs create` accepts `status`, `stub`, `startedAt`, `finishedAt` and `errorSummary`. Schema fields may have `type: ref` (optional `refKind`), validated against the product's artifact registry, linking and freezing the artifact and usable as a chart axis or `groupBy` key. Charts admit other versions of the same schema when every charted field keeps its value kind, unit and direction. These need the updated API.
+
+### Credentials (0.6.0)
+
+`auth login --token TOKEN` verifies a credential against the server and stores it for that server only, under your config directory and owner-readable; `auth status` shows which credential is in use and `auth logout` removes it. Global `--token` and `--org` (or `FIELDWORK_TOKEN` and `FIELDWORK_ORGANIZATION`) override it per command; an agent credential is bound to one organization and needs no `--org`. `whoami` reports the credential's organization and current permissions. Agent credentials are issued from the web app's Account page. Requires an API with authentication.
+
+### Hosted default, paging, chart series and schema backfill (0.7.0)
+
+The default server is the hosted service; a local one needs `--url` or `FIELDWORK_URL`. Lists and every stub lookup walk the API's paged `{ items, nextCursor }` responses, and `get`/`context` return child runs as a first page rather than an array. `charts series` and `charts frontier` save a raw chart's colouring and chosen frontier, and `schemas extend` accepts `backfill` to fill in fields a run predates on runs it re-pins, noted in `research.backfilled` and correctable with `runs update`. These need the updated API.
+
+### Release history
+
+`fieldwork changelog [--since VERSION] [--release VERSION]` prints recent releases offline, marking per change whether it needs an updated API. The package carries recent releases only; the repository's `docs/cli-changelog.md` is the full history. A newer client never upgrades a server, and the CLI cannot verify what an API provides.

package/dist/changelog.js

@@ -0,0 +1,137 @@
+export const fullHistory = 'docs/cli-changelog.md in the Fieldwork repository';
+export const entries = [
+    {
+        version: '0.7.0',
+        date: '2026-09-22',
+        status: 'prepared',
+        changes: [
+            {
+                summary: 'The default server is the hosted service, https://app.fieldworkledger.com, instead of http://127.0.0.1:4310. A local server needs --url or FIELDWORK_URL; a workspace set up against one keeps using it.',
+                requiresApi: false,
+            },
+            {
+                summary: 'Experiment and run lists, and every stub lookup behind get, record, update and delete, walk the paged { items, nextCursor } responses. 0.6.0 read the first page shape as an invalid collection against a current server.',
+                requiresApi: true,
+            },
+            {
+                summary: 'charts frontier CHART_ID --json {"runIds":[...]} saves the runs a scatter chart joins as its frontier, replacing any earlier choice. Chosen, never computed; only runs the chart plots are accepted.',
+                requiresApi: true,
+            },
+            {
+                summary: 'charts series CHART_ID --json {"series":...} colours a raw chart by a typed field, or by groups of runs you define (for a split no field records, such as ours against as shipped); null restores comparison-context series. charts create accepts series too.',
+                requiresApi: true,
+            },
+            {
+                summary: 'schemas extend accepts backfill: {field: {RUN_ID: value}} to fill in parameter or context fields a run predates -- added after it was recorded, by this extension or an earlier one -- finished runs included. Runs note them in research.backfilled, and a backfilled value can be corrected with runs update.',
+                requiresApi: true,
+            },
+        ],
+    },
+    {
+        version: '0.6.0',
+        date: '2026-09-20',
+        status: 'prepared',
+        changes: [
+            {
+                summary: 'fieldwork auth login, status and logout store one credential per server under your config directory, owner-readable only. Ordinary commands then need no --token. login verifies the credential before storing it, and status reports which source is in use.',
+                requiresApi: false,
+            },
+            {
+                summary: 'Global --token and --org send a credential and an organization with every request. An agent credential is bound to one organization, so --org is unnecessary for one.',
+                requiresApi: true,
+            },
+            {
+                summary: 'Authentication failures explain themselves: 401 reports a missing credential and 403 the wrong organization or a withdrawn grant, both stating that a retry will not help.',
+                requiresApi: true,
+            },
+        ],
+    },
+    {
+        version: '0.5.0',
+        date: '2026-09-18',
+        status: 'prepared',
+        changes: [
+            {
+                summary: 'runs list and experiments list select and project rows: --where FIELD=VALUE (also != >= <= > <, repeatable), --fields PATHS, --format tsv, and runs list --experiment REF. Selection and projection only; no values are computed.',
+                requiresApi: false,
+            },
+            {
+                summary: 'runs list and experiments list exclude superseded records (extras.superseded_by) and work under abandoned experiments by default; --include-superseded and --include-abandoned restore them. This changes the default output of an existing command.',
+                requiresApi: false,
+            },
+            {
+                summary: 'fieldwork changelog reports recent releases offline, marking which changes need an updated API.',
+                requiresApi: false,
+            },
+            {
+                summary: 'Network failures, timeouts and invalid server responses have distinct error codes and retry guidance; API failures retain the server request ID.',
+                requiresApi: false,
+            },
+            {
+                summary: 'runs record REF applies observations, extras, comparison context, artifacts, a status, an error summary or a logs URI in one call; the server reads the current revision, a result may be recorded directly from planned, and an identical revisionless retry reads back the committed result.',
+                requiresApi: true,
+            },
+            {
+                summary: 'runs create accepts status, stub, startedAt, finishedAt and errorSummary, so a finished or historical run is a single call. Dates are order-checked and never invented.',
+                requiresApi: true,
+            },
+            {
+                summary: 'Schema fields support type ref with optional refKind recipe or file, validated against the product artifact registry. A recorded ref links and freezes its artifact, and works as a bar X axis and groupBy key.',
+                requiresApi: true,
+            },
+            {
+                summary: 'Charts admit runs pinned to other versions of the same schema when every charted field keeps its value kind, unit and direction; schemaVersions "pinned" opts out, and charts data reports each version with its verdict.',
+                requiresApi: true,
+            },
+            {
+                summary: 'charts data leaves out runs marked extras.superseded_by, reporting each under excluded with the replacement named, so a pooled run can no longer be averaged in beside the per-set runs that replaced it and understate the spread.',
+                requiresApi: true,
+            },
+            {
+                summary: 'Experiment and run responses repeat schemaVersionId, varying, observations, comparisonContext, extras and artifactIds at the top level; research remains canonical.',
+                requiresApi: true,
+            },
+        ],
+    },
+];
+function order(version) {
+    return version.split('.').map(Number);
+}
+export function compareVersions(a, b) {
+    const [left, right] = [order(a), order(b)];
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference)
+            return difference;
+    }
+    return 0;
+}
+function invalid(message, hint) {
+    throw Object.assign(new Error(message), { code: 'UNKNOWN_VERSION', hint });
+}
+export function selectChangelog(cliVersion, options = {}) {
+    const oldest = entries[entries.length - 1].version;
+    for (const value of [options.since, options.release]) {
+        if (value !== undefined && !/^\d+(\.\d+)*$/.test(value))
+            invalid(`Not a version number: ${value}`, 'Use a dotted version such as 0.4.0.');
+    }
+    let selected = [...entries];
+    if (options.release) {
+        selected = selected.filter((entry) => entry.version === options.release);
+        if (!selected.length)
+            invalid(`Release ${options.release} is not bundled with this CLI`, `This package carries recent releases only, back to ${oldest}. See ${fullHistory}.`);
+    }
+    if (options.since)
+        selected = selected.filter((entry) => compareVersions(entry.version, options.since) > 0);
+    // An older --since must not read as "nothing else ever changed".
+    const truncated = !options.release && !!options.since && compareVersions(options.since, oldest) < 0;
+    return {
+        cliVersion,
+        recentOnly: true,
+        oldestBundled: oldest,
+        fullHistory,
+        ...(truncated ? { truncated: true } : {}),
+        note: `Recent releases only, back to ${oldest}${truncated ? `; changes before ${oldest} are not bundled` : ''}. requiresApi states what a change needs from the server, which this CLI cannot verify: a newer client does not upgrade an API.`,
+        entries: selected,
+    };
+}

package/dist/client.js

@@ -1,12 +1,85 @@
-export async function request(baseUrl, path, method = 'GET', body) {
-    const response = await fetch(`${baseUrl.replace(/\/$/, '')}/api/v1${path}`, {
-        method, headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(15000),
-    });
+const retryHint = (method) => method === 'GET'
+    ? 'This read is safe to retry.'
+    : 'The server may have committed this write. Inspect the target record before retrying.';
+export async function request(baseUrl, path, method = 'GET', body, credentials = {}) {
+    const origin = baseUrl.replace(/\/$/, '');
+    let response;
+    try {
+        response = await fetch(`${origin}/api/v1${path}`, {
+            method,
+            headers: {
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...(credentials.token ? { Authorization: `Bearer ${credentials.token}` } : {}),
+                ...(credentials.organization
+                    ? { 'X-Fieldwork-Organization': credentials.organization }
+                    : {}),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch (error) {
+        const timedOut = error instanceof Error && ['AbortError', 'TimeoutError'].includes(error.name);
+        // Named, because the server is resolved from a flag, two environment variables, a
+        // workspace file or a default, and "could not reach the server" leaves the reader to
+        // guess which of those was in force. The origin carries no credential: tokens travel
+        // in a header.
+        throw Object.assign(new Error(timedOut
+            ? `Request to ${origin} timed out after 15 seconds`
+            : `Could not reach the server at ${origin}`), {
+            code: timedOut ? 'REQUEST_TIMEOUT' : 'NETWORK_ERROR',
+            hint: retryHint(method),
+            cause: error,
+        });
+    }
     if (response.status === 204)
         return { deleted: true };
-    const data = await response.json();
+    let data;
+    try {
+        data = (await response.json());
+    }
+    catch (error) {
+        throw Object.assign(new Error(`Server returned an invalid response (HTTP ${response.status})`), {
+            code: 'INVALID_RESPONSE',
+            status: response.status,
+            hint: retryHint(method),
+            cause: error,
+        });
+    }
     if (!response.ok)
-        throw Object.assign(new Error(data.message ?? `HTTP ${response.status}`), { code: data.code ?? 'HTTP_ERROR', status: response.status, ...(data.details ? { details: data.details } : {}) });
+        throw Object.assign(new Error(data.message ?? `HTTP ${response.status}`), {
+            code: data.code ?? 'HTTP_ERROR',
+            status: response.status,
+            ...(response.status === 401 || response.status === 403
+                ? {
+                    hint: response.status === 401
+                        ? 'Supply a credential with --token, FIELDWORK_TOKEN, or workspace configuration. Retrying without one will not succeed.'
+                        : 'This credential is valid but not permitted here. Check the selected organization with --org or FIELDWORK_ORGANIZATION, and that its access has not been revoked.',
+                }
+                : {}),
+            ...(data.details ? { details: data.details } : {}),
+            ...(data.requestId ? { requestId: data.requestId } : {}),
+        });
     return data;
 }
+/** Every page of a paged collection.
+ *
+ * The CLI filters, groups and formats over whole collections -- `--where`, superseded and
+ * abandoned exclusions, field selection -- so a page of them would apply each filter to a
+ * page and call it the answer. Walking is the honest reading of the same request; when a
+ * campaign is large enough for that to hurt, the filters belong in the query.
+ */
+export async function requestAll(baseUrl, path, credentials = {}) {
+    const all = [];
+    let cursor = null;
+    do {
+        const separator = path.includes('?') ? '&' : '?';
+        const page = (await request(baseUrl, cursor ? `${path}${separator}cursor=${encodeURIComponent(cursor)}` : path, 'GET', undefined, credentials));
+        // A collection that is not paged answers with an array, and is its own only page.
+        if (Array.isArray(page))
+            return page;
+        all.push(...(page.items ?? []));
+        cursor = page.nextCursor ?? null;
+    } while (cursor);
+    return all;
+}

package/dist/credentials.js

@@ -0,0 +1,78 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function credentialsPath() {
+    const base = process.env['XDG_CONFIG_HOME'] || join(homedir(), '.config');
+    return join(base, 'fieldwork', 'credentials.json');
+}
+/** Origins are compared without a trailing slash so http://host and http://host/ agree. */
+const key = (url) => url.replace(/\/$/, '');
+function read() {
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return { version: 1, servers: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed?.servers && typeof parsed.servers === 'object'
+            ? { version: 1, servers: parsed.servers }
+            : { version: 1, servers: {} };
+    }
+    catch {
+        // A corrupted file must not lock the CLI out: an explicit --token or FIELDWORK_TOKEN
+        // still works, and `auth login` overwrites it.
+        return { version: 1, servers: {} };
+    }
+}
+export function storedCredential(url) {
+    return read().servers[key(url)];
+}
+export function storeCredential(url, credential) {
+    const path = credentialsPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const file = read();
+    file.servers[key(url)] = credential;
+    // Written before chmod, so the window where it exists with default permissions is as
+    // small as possible; the directory is already owner-only.
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+export function forgetCredential(url) {
+    const file = read();
+    if (!file.servers[key(url)])
+        return false;
+    delete file.servers[key(url)];
+    const path = credentialsPath();
+    if (Object.keys(file.servers).length === 0)
+        rmSync(path, { force: true });
+    else {
+        writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(path, 0o600);
+    }
+    return true;
+}
+/** Resolution order, matching how --url resolves: explicit, then environment, then stored.
+ *  The source is reported so `auth status` can say which one is in play -- the usual
+ *  confusion is a stale environment variable shadowing a fresh login. */
+export function resolveCredential(url, flags) {
+    if (flags.token)
+        return { token: flags.token, organization: flags.org, source: 'flag' };
+    const fromEnvironment = process.env['FIELDWORK_TOKEN'];
+    if (fromEnvironment)
+        return {
+            token: fromEnvironment,
+            organization: flags.org ?? process.env['FIELDWORK_ORGANIZATION'],
+            source: 'environment',
+        };
+    const stored = storedCredential(url);
+    if (stored)
+        return {
+            token: stored.token,
+            organization: flags.org ?? process.env['FIELDWORK_ORGANIZATION'] ?? stored.organization,
+            source: 'file',
+        };
+    return {
+        organization: flags.org ?? process.env['FIELDWORK_ORGANIZATION'],
+        source: 'none',
+    };
+}