@purveyors/cli 0.20.1 → 0.23.0

package/README.md

@@ -2,7 +2,7 @@
 
 Coffee intelligence from your terminal.
 
-`purvey` is the official CLI for [purveyors.io](https://purveyors.io). It gives coffee professionals, developers, and AI agents direct access to the Purveyors platform from the terminal: catalog search, inventory tracking, roast logging, sales records, tasting notes, and Artisan `.alog` import.
+`purvey` is the official CLI for [purveyors.io](https://purveyors.io). It gives coffee professionals, developers, and AI agents direct access to the Purveyors platform from the terminal: catalog search, price-index snapshots, procurement brief reads, inventory tracking, roast logging, sales records, tasting notes, and Artisan `.alog` import.
 
 Use `purvey --help` for quick command discovery, `purvey context` for the dense human-readable operator reference, `purvey manifest` for the preferred machine-readable contract, or `@purveyors/cli/manifest` in-process.
 
@@ -13,7 +13,7 @@ Use `purvey --help` for quick command discovery, `purvey context` for the dense
 - Runtime: Node.js 20+
 - No pre-existing session required: `auth`, `config`, `context`, `manifest`
 - Viewer role required: `catalog` (excluding structured process filters on `catalog search`)
-- Member role required: `inventory`, `roast`, `sales`, `tasting`
+- Member role required: `price-index`, `procurement`, `inventory`, `roast`, `sales`, `tasting`
 - Preferred machine-readable contract: `purvey manifest`
 - Dense human-readable reference: `purvey context`
 - Compatibility JSON alias: `purvey context --json`
@@ -62,7 +62,7 @@ The CLI is an agent-first product surface. Treat the binary, exported functions,
 ## Quick Start
 
 ```bash
-# 1. Authenticate before using catalog, inventory, roast, sales, or tasting commands
+# 1. Authenticate before using catalog, market intelligence, inventory, roast, sales, or tasting commands
 purvey auth login
 
 # For agents, CI, or remote machines, use headless flow:
@@ -135,7 +135,7 @@ All remote data commands require a valid authenticated session:
 
 - `catalog` requires the `viewer` role by default
 - `catalog search` structured process filters require the `member` role under the current session-authenticated CLI path
-- `inventory`, `roast`, `sales`, and `tasting` require the `member` role
+- `price-index`, `procurement`, `inventory`, `roast`, `sales`, and `tasting` require the `member` role under the session-authenticated CLI path
 
 `purvey` uses Google OAuth through purveyors.io.
 
@@ -174,10 +174,10 @@ Credentials are stored at `~/.config/purvey/credentials.json`.
 
 ### Auth roles
 
-| Role     | Access                                                                                                                                                                         |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `viewer` | `catalog search`, `catalog get`, `catalog stats`, excluding structured process filters                                                                                         |
-| `member` | All viewer commands, `catalog similar`, structured process filters on `catalog search`, plus `inventory`, `roast`, `sales`, `tasting` under the session-authenticated CLI path |
+| Role     | Access                                                                                                                                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `viewer` | `catalog search`, `catalog get`, `catalog stats`, excluding structured process filters                                                                                                                       |
+| `member` | All viewer commands, `catalog similar`, structured process filters on `catalog search`, plus `price-index`, `procurement`, `inventory`, `roast`, `sales`, `tasting` under the session-authenticated CLI path |
 
 `auth`, `config`, `context`, and `manifest` remain available without a pre-existing session.
 
@@ -412,6 +412,61 @@ Notes:
 - The command preserves `classification_version`, `query_strategy`, score dimensions, proof summaries, pricing metadata, and classification/blocker details supplied by the API.
 - `catalog stats` returns aggregate catalog metrics, not your personal inventory metrics.
 
+### price-index
+
+- `purvey price-index`
+
+`price-index` filters:
+
+- `--origin <origin>`
+- `--process <method>`
+- `--grade <grade>`
+- `--from <YYYY-MM-DD>`
+- `--to <YYYY-MM-DD>`
+- `--wholesale <true|false>`
+- `--page <n>`; 1-based page number
+- `--limit <n>`; results per page
+
+Examples:
+
+```bash
+purvey price-index --pretty
+purvey price-index --origin "Ethiopia" --from 2026-01-01 --to 2026-06-30 --json
+PARCHMENT_API_KEY="$PURVEYORS_API_KEY" purvey price-index --limit 25 --json
+```
+
+Notes:
+
+- `price-index` is backed by the canonical Parchment API `GET /v1/price-index` through `@purveyors/sdk`.
+- Session-token use requires the local `member` role; API-key use is accepted via `PARCHMENT_API_KEY` or `PURVEYORS_API_KEY` and PPI entitlement is enforced server-side.
+- `PARCHMENT_API_BASE_URL` overrides the canonical API base for this SDK-backed command. `PURVEYORS_BASE_URL` is also accepted for shared environment compatibility.
+
+### procurement
+
+- `purvey procurement list`
+- `purvey procurement get <id>`
+- `purvey procurement matches <id>`
+
+`procurement matches <id>` options:
+
+- `--page <n>`; 1-based page number
+- `--limit <n>`; matches per page
+
+Examples:
+
+```bash
+purvey procurement list --pretty
+purvey procurement get <brief-id> --pretty
+purvey procurement matches <brief-id> --page 2 --limit 50 --json
+PARCHMENT_API_KEY="$PURVEYORS_API_KEY" purvey procurement list --json
+```
+
+Notes:
+
+- Procurement reads are backed by the canonical Parchment API `/v1/procurement/briefs` endpoints through `@purveyors/sdk`.
+- Session-token use requires the local `member` role; API-key use is accepted via `PARCHMENT_API_KEY` or `PURVEYORS_API_KEY` and procurement access is enforced server-side.
+- Brief creation is intentionally not exposed here. It is a write path and belongs to the Phase 2 write build-out.
+
 ### inventory
 
 - `purvey inventory list`
@@ -769,8 +824,9 @@ Use the right ID for the right command.
 - `PURVEYORS_SUPABASE_URL`: override the Supabase project URL
 - `PURVEYORS_SUPABASE_ANON_KEY`: override the Supabase anon key
 - `PURVEYORS_BASE_URL`: override the Purveyors web base URL
-- `PURVEYORS_API_KEY`: API-key token used by API-backed catalog proof reads and paid-tier similarity reads when you want to call canonical API contracts without relying on the local OAuth session
-- `PARCHMENT_API_KEY`: alternate API-key variable accepted for the same API-backed proof and paid-tier similarity path
+- `PURVEYORS_API_KEY`: API-key token used by API-backed catalog proof reads, paid-tier similarity reads, and SDK-backed Parchment commands when you want to call canonical API contracts without relying on the local OAuth session
+- `PARCHMENT_API_KEY`: preferred API-key variable for SDK-backed Parchment commands; also accepted for API-backed proof and paid-tier similarity paths
+- `PARCHMENT_API_BASE_URL`: override the SDK-backed Parchment API base URL for `price-index` and `procurement` commands
 - `PURVEY_DEBUG`: enable verbose error output
 
 ## For AI agents
@@ -803,9 +859,10 @@ Agent integration rules of thumb:
 
 - Discover first with `purvey manifest`, then call the narrowest command or package subpath that fits the job.
 - Use `purvey context` when a human-readable operator summary is useful before tool selection.
-- Prefer OAuth session tokens for normal user workflows; use `PURVEYORS_API_KEY` or `PARCHMENT_API_KEY` only when you intentionally need the API-key catalog proof path or a paid-tier similarity path.
+- Prefer OAuth session tokens for normal user workflows; use `PURVEYORS_API_KEY` or `PARCHMENT_API_KEY` only when you intentionally need an API-key-backed Parchment path such as catalog proof, paid-tier similarity, price-index, or procurement reads.
 - Treat `--include-proof` as API output, not a local scoring feature. If a filter cannot round-trip through `/v1/catalog?include=proof`, the CLI rejects that invocation instead of returning misleading proof data.
 - Treat `catalog similar` as the canonical `/v1/catalog/{id}/similar` contract. Preserve the distinction between `canonical_candidates` and `similar_recommendations`; do not flatten or re-sort grouped results unless you have a specific downstream reason.
+- Treat `price-index` and `procurement` as SDK-backed canonical API reads. Do not add procurement create/write behavior to this command group until the Phase 2 write contract ships.
 
 ## Troubleshooting
 

package/dist/commands/price-index.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+/**
+ * `purvey price-index` — Parchment Price Index aggregate snapshots.
+ * Requires an authenticated session or API key with price-index entitlement.
+ */
+export declare function buildPriceIndexCommand(): Command;
+//# sourceMappingURL=price-index.d.ts.map

package/dist/commands/price-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price-index.d.ts","sourceRoot":"","sources":["../../src/commands/price-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAgDhD"}

package/dist/commands/price-index.js

@@ -0,0 +1,71 @@
+import { Command } from 'commander';
+import { outputData } from '../lib/output.js';
+import { withErrorHandling, PrvrsError } from '../lib/errors.js';
+import { createParchmentClient, unwrapParchment } from '../lib/parchment.js';
+function parsePositiveInt(rawValue, flag) {
+    const parsed = Number(rawValue.trim());
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new PrvrsError('INVALID_ARGUMENT', `Invalid ${flag}: "${rawValue}". Must be a positive integer.`);
+    }
+    return parsed;
+}
+function parseWholesale(rawValue) {
+    const normalized = rawValue.trim().toLowerCase();
+    if (normalized === 'true')
+        return 'true';
+    if (normalized === 'false')
+        return 'false';
+    throw new PrvrsError('INVALID_ARGUMENT', `Invalid --wholesale: "${rawValue}". Must be "true" or "false".`);
+}
+/**
+ * `purvey price-index` — Parchment Price Index aggregate snapshots.
+ * Requires an authenticated session or API key with price-index entitlement.
+ */
+export function buildPriceIndexCommand() {
+    const priceIndex = new Command('price-index')
+        .description('Fetch Parchment Price Index aggregate snapshots (requires price-index access)')
+        .option('--origin <origin>', 'Filter by origin')
+        .option('--process <method>', 'Filter by process method')
+        .option('--grade <grade>', 'Filter by grade')
+        .option('--from <date>', 'Include snapshots on/after this ISO date (YYYY-MM-DD)')
+        .option('--to <date>', 'Include snapshots on/before this ISO date (YYYY-MM-DD)')
+        .option('--wholesale <true|false>', 'Filter by wholesale pricing scope')
+        .option('--page <n>', '1-based page number')
+        .option('--limit <n>', 'Results per page')
+        .addHelpText('after', `
+Examples:
+  purvey price-index --pretty
+  purvey price-index --origin "Ethiopia" --json
+  purvey price-index --from 2026-01-01 --to 2026-06-30 --pretty
+  purvey price-index --wholesale true --limit 25 --json
+
+Notes:
+  Requires a Purveyors session or API key with price-index (PPI) access.
+  Set PARCHMENT_API_KEY or PURVEYORS_API_KEY to use an API key instead of the logged-in session.`)
+        .action(withErrorHandling(async (opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        const query = {};
+        if (opts.origin !== undefined)
+            query.origin = opts.origin;
+        if (opts.process !== undefined)
+            query.process = opts.process;
+        if (opts.grade !== undefined)
+            query.grade = opts.grade;
+        if (opts.from !== undefined)
+            query.from = opts.from;
+        if (opts.to !== undefined)
+            query.to = opts.to;
+        if (opts.wholesale !== undefined)
+            query.wholesale = parseWholesale(opts.wholesale);
+        if (opts.page !== undefined)
+            query.page = parsePositiveInt(opts.page, '--page');
+        if (opts.limit !== undefined)
+            query.limit = parsePositiveInt(opts.limit, '--limit');
+        const client = await createParchmentClient('member');
+        const result = await client.priceIndex.list(query);
+        const data = unwrapParchment(result, 'price-index');
+        outputData(data, globalOpts);
+    }));
+    return priceIndex;
+}
+//# sourceMappingURL=price-index.js.map

package/dist/commands/price-index.js.map

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

package/dist/commands/procurement.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * `purvey procurement` — read saved sourcing briefs from the canonical API.
+ * Brief creation is a write and is handled by the Phase 2 write build-out
+ * (PADR-0016), not by this read surface.
+ */
+export declare function buildProcurementCommand(): Command;
+//# sourceMappingURL=procurement.d.ts.map

package/dist/commands/procurement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"procurement.d.ts","sourceRoot":"","sources":["../../src/commands/procurement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CA4EjD"}

package/dist/commands/procurement.js

@@ -0,0 +1,72 @@
+import { Command } from 'commander';
+import { outputData } from '../lib/output.js';
+import { withErrorHandling, PrvrsError } from '../lib/errors.js';
+import { createParchmentClient, unwrapParchment } from '../lib/parchment.js';
+function parsePositiveInt(rawValue, flag) {
+    const parsed = Number(rawValue.trim());
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new PrvrsError('INVALID_ARGUMENT', `Invalid ${flag}: "${rawValue}". Must be a positive integer.`);
+    }
+    return parsed;
+}
+/**
+ * `purvey procurement` — read saved sourcing briefs from the canonical API.
+ * Brief creation is a write and is handled by the Phase 2 write build-out
+ * (PADR-0016), not by this read surface.
+ */
+export function buildProcurementCommand() {
+    const procurement = new Command('procurement').description('Read saved sourcing briefs and their catalog matches');
+    // procurement list
+    procurement
+        .command('list')
+        .description('List your saved sourcing briefs')
+        .addHelpText('after', `
+Examples:
+  purvey procurement list --pretty
+  purvey procurement list --json | jq '.data'`)
+        .action(withErrorHandling(async (_opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        const client = await createParchmentClient('member');
+        const result = await client.procurement.briefs.list();
+        const data = unwrapParchment(result, 'procurement list');
+        outputData(data, globalOpts);
+    }));
+    // procurement get <id>
+    procurement
+        .command('get <id>')
+        .description('Get a single saved sourcing brief by id')
+        .addHelpText('after', `
+Examples:
+  purvey procurement get 3f9a2c10-... --pretty`)
+        .action(withErrorHandling(async (id, _opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        const client = await createParchmentClient('member');
+        const result = await client.procurement.briefs.get(id);
+        const data = unwrapParchment(result, 'procurement get');
+        outputData(data, globalOpts);
+    }));
+    // procurement matches <id>
+    procurement
+        .command('matches <id>')
+        .description('Run a saved brief against the catalog and page through matches')
+        .option('--page <n>', '1-based page number (default 1)')
+        .option('--limit <n>', 'Matches per page (max 100; default 25)')
+        .addHelpText('after', `
+Examples:
+  purvey procurement matches 3f9a2c10-... --pretty
+  purvey procurement matches 3f9a2c10-... --page 2 --limit 50 --json`)
+        .action(withErrorHandling(async (id, opts, cmd) => {
+        const globalOpts = cmd.optsWithGlobals();
+        const query = {};
+        if (opts.page !== undefined)
+            query.page = parsePositiveInt(opts.page, '--page');
+        if (opts.limit !== undefined)
+            query.limit = parsePositiveInt(opts.limit, '--limit');
+        const client = await createParchmentClient('member');
+        const result = await client.procurement.briefs.matches(id, query);
+        const data = unwrapParchment(result, 'procurement matches');
+        outputData(data, globalOpts);
+    }));
+    return procurement;
+}
+//# sourceMappingURL=procurement.js.map

package/dist/commands/procurement.js.map

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

package/dist/commands/roast.d.ts

@@ -1,6 +1,32 @@
 import { Command } from 'commander';
-import type { RoastProfile, TemperatureEntry, RoastEventEntry } from '../lib/roast.js';
+import type { RoastProfile, TemperatureEntry, RoastEventEntry, ImportRoastResult } from '../lib/roast.js';
+import type { WatchRoastImporter } from '../lib/interactive/watch.js';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { components } from '@purveyors/sdk';
+/** Canonical `POST /v1/roasts/imports` response payload. */
+type RoastImportPayload = components['schemas']['RoastImportResponse'];
 export type { RoastProfile, TemperatureEntry, RoastEventEntry };
+/**
+ * Map the canonical Parchment `roasts.import` response onto the CLI's existing
+ * {@link ImportRoastResult} output shape, so `--pretty` and machine output stay
+ * stable now that Artisan parsing and persistence happen server-side.
+ *
+ * `RoastDetailResource` surfaces only charge / first-crack / drop as top-level
+ * time columns, but the full Artisan milestone set (dry-end, second-crack
+ * start/end, cool) is persisted as milestone roast events. Recover those from
+ * `roast.events` so JSON and `--pretty` output keep the same milestone timing
+ * the pre-SDK local importer exposed, without re-parsing the `.alog` locally.
+ */
+export declare function mapSdkImportResult(payload: RoastImportPayload, fallbackCoffeeId: number, fallbackBatchName: string): ImportRoastResult;
+/**
+ * Build the roast importer used by `purvey roast watch`. Each import resolves
+ * the current member session token at call time (so long-running watch sessions
+ * survive token refresh) and forwards the raw `.alog` to the canonical Parchment
+ * API via the SDK, which parses and persists the roast server-side. The session
+ * JWT is pinned per request so an exported PARCHMENT_API_KEY/PURVEYORS_API_KEY
+ * for another account cannot authorize a write against the session user's beans.
+ */
+export declare function createWatchRoastImporter(supabase: SupabaseClient): WatchRoastImporter;
 /**
  * `purvey roast` — Browse and manage your roast profiles.
  * Requires member+ authentication.

package/dist/commands/roast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roast.d.ts","sourceRoot":"","sources":["../../src/commands/roast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AAQzB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAIhE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAw6B3C"}
+{"version":3,"file":"roast.d.ts","sourceRoot":"","sources":["../../src/commands/roast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAO5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD,4DAA4D;AAC5D,KAAK,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,qBAAqB,CAAC,CAAC;AAGvE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAC3B,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,EAAE,MAAM,GACxB,iBAAiB,CAyDnB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,GAAG,kBAAkB,CAwBrF;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAy9B3C"}

package/dist/commands/roast.js

@@ -3,14 +3,110 @@ import * as p from '@clack/prompts';
 import { access, readFile } from 'fs/promises';
 import { basename } from 'path';
 import { outputData, info, success } from '../lib/output.js';
-import { withErrorHandling, PrvrsError } from '../lib/errors.js';
+import { withErrorHandling, PrvrsError, AuthError } from '../lib/errors.js';
 import { requireAuth } from '../lib/auth-guard.js';
 import { confirm, todayIso } from '../lib/prompts.js';
-import { listRoasts, getRoast, createRoast, deleteRoast, updateRoast, importRoastFromFile, } from '../lib/roast.js';
+import { listRoasts, getRoast, createRoast, deleteRoast, updateRoast } from '../lib/roast.js';
 import { pickBean, guardCancel } from '../lib/interactive/forms.js';
 import { normalizePathInput } from '../lib/path-input.js';
 import { startWatch, loadWatchSession } from '../lib/interactive/watch.js';
 import { getConfigValue } from '../lib/config.js';
+import { createParchmentClient, resolveParchmentSessionTokenIfAvailable, unwrapParchment, } from '../lib/parchment.js';
+/**
+ * Map the canonical Parchment `roasts.import` response onto the CLI's existing
+ * {@link ImportRoastResult} output shape, so `--pretty` and machine output stay
+ * stable now that Artisan parsing and persistence happen server-side.
+ *
+ * `RoastDetailResource` surfaces only charge / first-crack / drop as top-level
+ * time columns, but the full Artisan milestone set (dry-end, second-crack
+ * start/end, cool) is persisted as milestone roast events. Recover those from
+ * `roast.events` so JSON and `--pretty` output keep the same milestone timing
+ * the pre-SDK local importer exposed, without re-parsing the `.alog` locally.
+ */
+export function mapSdkImportResult(payload, fallbackCoffeeId, fallbackBatchName) {
+    const roast = payload.data.roast;
+    const summary = payload.data.import;
+    const milestones = {};
+    if (roast.charge_time != null)
+        milestones.charge = roast.charge_time;
+    if (roast.fc_start_time != null)
+        milestones.fc_start = roast.fc_start_time;
+    if (roast.fc_end_time != null)
+        milestones.fc_end = roast.fc_end_time;
+    if (roast.drop_time != null)
+        milestones.drop = roast.drop_time;
+    // Fill any remaining markers (notably dry_end / sc_start / sc_end / cool,
+    // which have no dedicated column) from the canonical milestone events. The
+    // top-level columns above win; events only backfill gaps.
+    const MILESTONE_KEYS = [
+        'charge',
+        'dry_end',
+        'fc_start',
+        'fc_end',
+        'sc_start',
+        'sc_end',
+        'drop',
+        'cool',
+    ];
+    for (const event of roast.events ?? []) {
+        const key = event.event_string;
+        if (key != null &&
+            MILESTONE_KEYS.includes(key) &&
+            milestones[key] == null &&
+            event.time_seconds != null) {
+            milestones[key] = event.time_seconds;
+        }
+    }
+    const totalTime = roast.total_roast_time ?? 0;
+    const temperatureUnit = roast.temperature_unit === 'C' ? 'C' : 'F';
+    return {
+        success: true,
+        message: `Imported ${summary.temperaturePoints} data points, ${summary.milestoneEvents} milestones, ${summary.controlEvents} control events`,
+        milestones,
+        phases: {
+            drying_percent: roast.dry_percent ?? 0,
+            maillard_percent: roast.maillard_percent ?? 0,
+            development_percent: roast.development_percent ?? 0,
+            total_time_seconds: totalTime,
+        },
+        total_time: totalTime,
+        temperature_unit: temperatureUnit,
+        milestone_events: summary.milestoneEvents,
+        control_events: summary.controlEvents,
+        roast_id: roast.roast_id,
+        batch_name: roast.batch_name ?? fallbackBatchName,
+        coffee_name: roast.coffee_name ?? '',
+        coffee_id: roast.coffee_id ?? fallbackCoffeeId,
+    };
+}
+/**
+ * Build the roast importer used by `purvey roast watch`. Each import resolves
+ * the current member session token at call time (so long-running watch sessions
+ * survive token refresh) and forwards the raw `.alog` to the canonical Parchment
+ * API via the SDK, which parses and persists the roast server-side. The session
+ * JWT is pinned per request so an exported PARCHMENT_API_KEY/PURVEYORS_API_KEY
+ * for another account cannot authorize a write against the session user's beans.
+ */
+export function createWatchRoastImporter(supabase) {
+    return async (args) => {
+        const { data: { session }, } = await supabase.auth.getSession();
+        if (!session?.access_token) {
+            throw new AuthError('Session expired mid-watch. Run `purvey auth login` and retry.');
+        }
+        const client = await createParchmentClient('member', session.access_token);
+        const payload = unwrapParchment(await client.roasts.import({
+            fileContent: args.fileContent,
+            fileName: args.fileName,
+            coffeeId: args.coffeeId,
+            batchName: args.batchName,
+            ozIn: args.ozIn,
+            roastNotes: args.roastNotes,
+            roastTargets: args.roastTargets,
+            fileSize: Buffer.byteLength(args.fileContent, 'utf-8'),
+        }), 'roast import');
+        return mapSdkImportResult(payload, args.coffeeId, args.batchName);
+    };
+}
 // ─── Command builder ──────────────────────────────────────────────────────────
 /**
  * `purvey roast` — Browse and manage your roast profiles.
@@ -433,7 +529,19 @@ Required: <file> path and --coffee-id (unless using --form)
             const targetsStr = String(roastTargetsRaw).trim();
             const spin = p.spinner();
             spin.start('Importing roast data...');
-            const result = await importRoastFromFile(supabase, userId, {
+            // Parse + persist happen server-side via the canonical Parchment
+            // API. `bean` was resolved through the authenticated Supabase
+            // session above (pickBean), so the import must run under that same
+            // session identity. Pin the request to the session access token
+            // instead of letting an exported PARCHMENT_API_KEY/PURVEYORS_API_KEY
+            // for another account authorize an import against a coffeeId owned
+            // by the session user.
+            const { data: { session: formSession }, } = await supabase.auth.getSession();
+            if (!formSession?.access_token) {
+                throw new AuthError('Session expired mid-import. Run `purvey auth login` and retry.');
+            }
+            const client = await createParchmentClient('member', formSession.access_token);
+            const payload = unwrapParchment(await client.roasts.import({
                 fileContent,
                 fileName,
                 coffeeId: bean.id,
@@ -441,7 +549,9 @@ Required: <file> path and --coffee-id (unless using --form)
                 ozIn,
                 roastNotes: notesStr !== '' ? notesStr : undefined,
                 roastTargets: targetsStr !== '' ? targetsStr : undefined,
-            });
+                fileSize: Buffer.byteLength(fileContent, 'utf-8'),
+            }), 'roast import');
+            const result = mapSdkImportResult(payload, bean.id, batchName);
             spin.stop('Done');
             p.outro(`Roast imported! Profile #${result.roast_id} created.`);
             outputData(result, globalOpts);
@@ -462,9 +572,7 @@ Required: <file> path and --coffee-id (unless using --form)
         // 2. Read file content
         const fileContent = await readFile(filePath, 'utf-8');
         const fileName = basename(filePath);
-        // 3. Authenticate
-        const { supabase, userId } = await requireAuth('member');
-        // 4. Parse --coffee-id
+        // 3. Parse --coffee-id
         if (!opts.coffeeId) {
             throw new PrvrsError('INVALID_ARGUMENT', 'Missing --coffee-id. Use --form for interactive mode.');
         }
@@ -472,7 +580,7 @@ Required: <file> path and --coffee-id (unless using --form)
         if (isNaN(coffeeId) || coffeeId <= 0) {
             throw new PrvrsError('INVALID_ARGUMENT', `Invalid --coffee-id: "${opts.coffeeId}".`);
         }
-        // 5. Parse --oz-in if provided
+        // 4. Parse --oz-in if provided
         let ozIn;
         if (opts.ozIn !== undefined) {
             ozIn = parseFloat(opts.ozIn);
@@ -483,8 +591,17 @@ Required: <file> path and --coffee-id (unless using --form)
         const roastTargets = typeof opts.roastTargets === 'string' && opts.roastTargets.trim() !== ''
             ? opts.roastTargets.trim()
             : undefined;
-        // 6. Run the import
-        const result = await importRoastFromFile(supabase, userId, {
+        // 5. Run the import via the canonical Parchment API. The server
+        // parses the raw .alog, creates the roast, and persists the curve +
+        // events atomically; identity is resolved from the bearer token
+        // (session JWT or owner-bound API key), so there is no local write.
+        // Prefer an existing logged-in member session for flag mode too:
+        // users often copy --coffee-id from session-scoped inventory, and an
+        // exported API key for another account must not steal that request.
+        // If no valid session exists, the API-key-only path still works.
+        const sessionToken = await resolveParchmentSessionTokenIfAvailable('member');
+        const client = await createParchmentClient('member', sessionToken);
+        const payload = unwrapParchment(await client.roasts.import({
             fileContent,
             fileName,
             coffeeId,
@@ -492,8 +609,10 @@ Required: <file> path and --coffee-id (unless using --form)
             ozIn,
             roastNotes: opts.roastNotes,
             roastTargets,
-        });
-        // 7. Output
+            fileSize: Buffer.byteLength(fileContent, 'utf-8'),
+        }), 'roast import');
+        const result = mapSdkImportResult(payload, coffeeId, opts.batchName ?? '');
+        // 6. Output
         if (globalOpts.pretty) {
             printImportPretty(result, coffeeId);
         }
@@ -537,6 +656,7 @@ Notes:
 `)
         .action(withErrorHandling(async (directory, opts) => {
         const { supabase, userId } = await requireAuth('member');
+        const roastImporter = createWatchRoastImporter(supabase);
         const parseCommitMode = (value, fallback = 'batch') => {
             if (value === undefined || value === null || String(value).trim() === '') {
                 return fallback;
@@ -575,7 +695,7 @@ Notes:
                 ozIn: saved.ozIn,
                 roastNotes: saved.roastNotes,
                 roastTargets: saved.roastTargets,
-            });
+            }, { roastImporter });
             return;
         }
         // ── Interactive form mode ────────────────────────────────────────────
@@ -690,7 +810,7 @@ Notes:
                 ozIn: parseOptionalPositiveNumber(ozInRaw, 'green weight'),
                 roastTargets: String(roastTargetsRaw).trim() !== '' ? String(roastTargetsRaw).trim() : undefined,
                 roastNotes: String(roastNotesRaw).trim() !== '' ? String(roastNotesRaw).trim() : undefined,
-            });
+            }, { roastImporter });
             return;
         }
         // ── Flag-based mode ──────────────────────────────────────────────────
@@ -751,7 +871,7 @@ Notes:
             ozIn,
             roastNotes,
             roastTargets,
-        });
+        }, { roastImporter });
     }));
     return roast;
 }
@@ -781,6 +901,7 @@ function printImportPretty(result, coffeeId) {
             fc_start: 'FC Start',
             fc_end: 'FC End',
             sc_start: 'SC Start',
+            sc_end: 'SC End',
             drop: 'Drop',
             cool: 'Cool',
         };