@assethub/cli 0.1.6 → 0.1.8

package/README.md

@@ -2,6 +2,258 @@
 
 Command line interface for AssetHub.
 
+## Agent generation with canvas history
+
+This release uses the Internal `api_canvas_execution` gate. Run `assethub capabilities`
+first. Image, mesh, parts split, and production analyze/execute/automation refuse to dispatch if canvas history is unavailable.
+The current public API remains compatible with clients that omit `executionContext`.
+
+```sh
+assethub image generate --prompt "small stylized robot" --agent my-agent --wait > image.json
+CANVAS_ID=$(jq -r '.execution.canvas.id' image.json)
+IMAGE_ASSET_ID=$(jq -r '.execution.outputs[0].assetId' image.json)
+IMAGE_RUN_ID=$(jq -r '.execution.runId' image.json)
+assethub mesh generate --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" \
+  --derived-from-run "$IMAGE_RUN_ID" --agent my-agent --wait > mesh.json
+assethub graph show --canvas "$CANVAS_ID"
+assethub runs list --canvas "$CANVAS_ID"
+assethub canvas open "$CANVAS_ID"
+```
+
+Without `--canvas`, the first generation creates one canvas per real working
+directory, API origin and organization. `canvas use <id>` changes the selection.
+An inaccessible selected canvas is an error; the CLI does not silently make another.
+`canvas open` prints JSON and opens a browser only in a terminal.
+
+Each generation returns `execution` with the canvas URL, run/job IDs, stable output
+asset IDs, history status, and credit usage when available. History persists while
+all browsers are closed. Uploaded images are promoted to owned durable assets.
+Use `--input-json @request.json` for a complete request, or the existing file/stdin/
+source flags. A `source create` or `files import` JSON response can be passed to
+`--source-json @source.json`; generated asset IDs can be passed to `--source-id`.
+
+The CLI saves each request before dispatch under `~/.assethub/state/operations`
+(or `ASSETHUB_CLI_STATE_DIR`). Those files contain inputs, never API keys. Keep the
+state directory private. `--operation-id <uuid>` supplies an operation identity;
+retries and `runs resume <operation-id>` reuse its identical body and key. A new
+candidate needs a new operation ID. `runs watch <run-id>` only reads status.
+
+stdout contains final JSON; stderr contains progress. Exit codes are 0 for accepted/
+completed, 1 for terminal failure/partial, 2 for input/auth/capability/budget errors,
+3 for timeout/history pending/needs review, and 130 for Ctrl-C. Timeout and Ctrl-C
+leave server execution running and return known identities.
+
+External agents can evaluate downloaded artifacts with their own tools and store
+an assessment without starting another model call:
+
+```sh
+assethub evaluations submit --canvas "$CANVAS_ID" --artifact "$IMAGE_ASSET_ID" \
+  --report ./evaluation.json --agent my-agent --require-pass
+assethub evaluations list --canvas "$CANVAS_ID"
+assethub graph lineage --canvas "$CANVAS_ID" --artifact "$IMAGE_ASSET_ID"
+assethub graph export --canvas "$CANVAS_ID" --out ./graph.json
+```
+
+`evaluation.json` requires the strict report fields `schemaVersion`,
+`rubric`, `verdict: pass|fail|needs_review`, `criteria`, `referenceAssetIds`, and
+`evidenceAssetIds` for comparable reports. The server records `agent_submission`
+and authenticated actor provenance. This never counts as human approval.
+`--require-pass` returns 1 for fail and 3 for missing/needs-review verdicts.
+
+For example, an agent that has not inspected the output yet can submit:
+
+```json
+{
+  "schemaVersion": "assethub.evaluation-submission.v1",
+  "rubric": {"id": "asset-quality", "version": "1"},
+  "verdict": "needs_review",
+  "criteria": [
+    {
+      "id": "visual-quality",
+      "verdict": "needs_review",
+      "reason": "Artifact inspection is pending."
+    }
+  ],
+  "referenceAssetIds": [],
+  "evidenceAssetIds": []
+}
+```
+
+Replace the verdict and reason with the actual assessment after inspecting the
+artifact; reference and evidence IDs must belong to the authenticated organization.
+
+Existing parts commands use the same canvas and durable operation storage:
+
+```sh
+assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V1.5 --wait
+# Select only the parts to execute; --all-ready selects all ready tasks.
+assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V1.5 --all-ready --wait
+# Internal V3.6.1 runs the complete graph split through one analyze receipt.
+assethub production agents
+assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V3.6.1 --all-ready --wait
+assethub production automation --canvas "$CANVAS_ID" --input-json @batch.json --wait
+```
+
+`parts split` keeps separate analysis and selected-part execution phases. Each phase
+has its own saved operation ID, with the execution linked to the analysis run.
+For Internal `V3.6.1` (`V3.6.1 Primary Images First`), analysis runs the complete
+Artifact Graph split. `--all-ready` waits for that one receipt and does not start a
+second production execution. Resume an interrupted graph split with
+`runs resume <operation-id>`; `--task-id`, `--mission-id`,
+`--part-extraction-mode`, and classic `--order-id` continuation are unsupported.
+Automation runs the existing complete batch pipeline, including mesh generation;
+its `images[]` share the selected canvas. `batch.json` uses the existing automation
+request shape, including `agentVersion`, `images` (owned `imageAssetId`, `uploadId`,
+or an `imageUrl` to import), `config`, and optional `maxCostCredits`.
+An uncertain Trigger acknowledgement remains recoverable as `needs_review` with
+pending history; retrying the same operation never silently launches another run.
+
+`evaluate list` discovers server evaluators. Server evaluation dispatch is currently
+unavailable. Graph exports are bounded to 100 runs/evaluations and 1,000 nodes;
+truncated exports require `--allow-truncated`. Other commands, including production run/intervene, rig and retopology,
+retain their existing API behavior and do not yet create these receipts.
+`autopilot --demo` is an experimental demo requiring the AssetHub monorepo and its unpublished development dependency `@assethub/autopilot-core`. Standalone project workflow commands do not require or install it. Autonomous budgeted improvement is a later stage.
+
+## Storyboard project workflow
+
+These API-key commands work from the standalone CLI. Canvas/context commands use
+`api_canvas_execution`; native moodboards additionally require an internal actor
+with `moodboard_style_reference_enabled`. Select a key belonging to the intended
+workspace before uploading source material. API keys are never part of context.
+
+```sh
+# No API key is needed for local extraction. Optional dependencies are reported.
+assethub project ingest ./client-sources --out-dir ./extracted --exclude-dir generated
+assethub canvas create --name "Storyboard scene study" > canvas.json
+CANVAS_ID=$(jq -r .id canvas.json)
+assethub canvas import --canvas "$CANVAS_ID" --file ./extracted/storyboard.png > storyboard.json
+assethub canvas import --canvas "$CANVAS_ID" --file ./character-face.png > character.json
+assethub canvas import --canvas "$CANVAS_ID" --file ./primary-style.png > style.json
+
+# Supply prompt + source text + imageAssetIds in analysis-request.json.
+# Keep facts, uncertain identities and proposed backgrounds separate.
+assethub language vision --input-json @analysis-request.json \
+  --operation-id 61e3a99c-30b7-4f41-8d57-2789ccdc7c92 --out analysis.json
+
+# Prepare context.json from the inspected source facts and analysis.
+assethub canvas context put --canvas "$CANVAS_ID" --file ./context.json --if-version 0
+assethub canvas context get --canvas "$CANVAS_ID" --out ./recovered-context.json
+assethub moodboard create --input-json @moodboard.json > board.json
+BOARD_ID=$(jq -r .id board.json)
+assethub moodboard analyze "$BOARD_ID" --wait > revision.json
+REVISION_ID=$(jq -r .id revision.json)
+assethub image generate --canvas "$CANVAS_ID" --context "$CANVAS_ID" \
+  --moodboard-revision "$REVISION_ID" --prompt "Reconstruct this storyboard as a 3D scene" \
+  --wait --download --out-dir ./generated > generated.json
+SOURCE_ID=$(jq -r .assetId storyboard.json)
+OUTPUT_ID=$(jq -r '.execution.outputs[0].assetId' generated.json)
+assethub canvas compare --canvas "$CANVAS_ID" --source-id "$SOURCE_ID" \
+  --asset-id "$OUTPUT_ID" --out ./comparison.html
+assethub evaluations submit --canvas "$CANVAS_ID" --artifact "$OUTPUT_ID" \
+  --report ./review.json --agent my-agent
+```
+
+`project ingest` extracts PDF text/pages, workbook cells and embedded images,
+representative video frames, and image/text sources. It writes `summary.json`,
+`text.md` and `images.json` with source paths, hashes and extraction metadata.
+Dependencies (Poppler, ffmpeg and Python 3) are detected, never installed. Partial
+extraction exits 3 and reports missing dependencies; filenames do not establish
+whether a picture is a storyboard or a 3D reference. Original files stay unchanged.
+
+A context document is an extensible JSON object:
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "EP013 s150",
+  "instructions": {
+    "must": ["Preserve the original character face and pose"],
+    "avoid": ["Generic replacement characters"]
+  },
+  "sources": [
+    {
+      "key": "storyboard",
+      "remoteAssetId": "<owned-image-uuid>",
+      "generationUse": "required"
+    }
+  ],
+  "generationPlan": {"requiredSourceKeys": ["storyboard"]},
+  "sourceFacts": [
+    "Facts established by the original storyboard and story text"
+  ],
+  "inferences": [
+    {"proposal": "Background inferred from story", "status": "proposed"}
+  ],
+  "reviewState": {"status": "awaiting_creator_review"}
+}
+```
+
+`context get --out` writes the document for editing and reuse; stdout contains its
+version/hash envelope. Updating changed content requires `--if-version N` from the
+last read. Image generation pins the current version by default; `--context-version`
+and repeated `--context-source` explicitly select a version and source keys. Required
+references, labelled instructions and source facts are added by the server, and their
+IDs/version/hash are recorded on the run. Retry an uncertain generation with
+`runs resume <operation-id>` to preserve the original pinned inputs.
+
+`moodboard.json` contains `name`, `assetIds` (maximum 12),
+`representativeAssetIds` (maximum 3, all included in assetIds), and optional
+`userNote`. `update <board-id> --input-json @file` creates a new immutable revision;
+`get`, `list`, and `archive` manage existing boards. Analysis uses the existing
+8-credit vision plan for a new attempt, resumes an active job, and reuses a ready
+revision. The combined generation limit is **6 content and style images**: five identity/storyboard references leave room
+for one style representative.
+
+Image import persists upload identity before registration and recovers the same
+asset after an uncertain response; `--upload-id` resumes a known completed upload.
+Identical moodboard creation input uses the same operation identity; supply a fresh
+`--operation-id` when intentionally creating another identical board. Language
+commands require a UUID operation ID: reuse it with the same input after a timeout.
+
+Comparisons are portable HTML with embedded image bytes and a SHA-256 provenance
+sidecar. They remain `awaiting_creator_review`; an agent evaluation is not creator
+approval. Native project assets and generation history are saved in AssetHub.
+`canvas layout` appends native image nodes and source/output edges through the
+authoritative canvas room (Internal rollout). It preserves matching existing nodes
+and rejects identity collisions. `canvas import` alone preserves an asset without
+changing layout. Use the owned asset IDs returned by import or generation, including `image_...` IDs.
+For example, create `layout.json` with those IDs:
+
+```json
+{
+  "images": [
+    {
+      "assetId": "<storyboard-asset-id>",
+      "role": "source",
+      "x": 0,
+      "y": 0,
+      "name": "Original storyboard"
+    },
+    {
+      "assetId": "<generated-asset-id>",
+      "role": "output",
+      "x": 600,
+      "y": 0,
+      "name": "Generated candidate — review pending"
+    }
+  ],
+  "connections": [
+    {
+      "sourceAssetId": "<storyboard-asset-id>",
+      "targetAssetId": "<generated-asset-id>"
+    }
+  ]
+}
+```
+
+```sh
+assethub canvas layout --canvas "$CANVAS_ID" --input-json @layout.json
+```
+
+Legacy `workspace --internal` commands and the experimental autopilot demo are
+not available in the standalone distribution. Use the authenticated public
+`canvas`, `moodboard`, and `canvas context` commands described above.
+
 ```sh
 export ASSETHUB_API_KEY=ah_live_xxx
 
@@ -13,8 +265,39 @@ assethub mesh generate --file ./input.png --wait
 assethub jobs watch job_123 --download --out-dir ./out/job
 assethub parts split --file ./input.png --part-extractor "V1.5" --wait --all-ready --download --out-dir ./out/parts
 assethub parts compare --file ./input.png --preprocess-prompt "clean white background, centered product photo" --part-extractor "V1.5" --wait --all-ready
+assethub runs upload ./out/pluffy-run-2026-07-30 --dry-run
 ```
 
+Uploading a local artifact-graph run:
+
+```sh
+# Validate the run folder without sending anything.
+assethub runs upload ./out/pluffy-run-2026-07-30 --dry-run
+
+# Upload it. Blobs go first, one at a time, then the snapshot.
+assethub runs upload ./out/pluffy-run-2026-07-30 --tag pluffy --description "V3 humanoid"
+```
+
+`<path>` is an `ag.graph-folder.v1` folder — the directory holding
+`manifest.json`, `nodes.jsonl`, `edges.jsonl` and `blobs/`. The wire format is
+`ag.registry.v1`, the same document the artifact-graph registry accepts, so one
+folder can be published to either destination without conversion.
+
+- `--dry-run` runs every local check and prints what _would_ be sent. A folder
+  whose manifest no longer matches its own `nodes.jsonl`, whose blob table
+  disagrees with the graph, or which exceeds the per-request size ceilings is
+  rejected here rather than halfway through an upload.
+- Uploads are resumable. Each blob is checked against the server before it is
+  sent, and blob storage is content-addressed, so re-running the identical
+  command after a failure sends only what is still missing.
+- `--graph-id` / `--stream-id` / `--rev` override the identity derived from the
+  folder name and `manifest.source`. Re-uploading the same revision with
+  different content is refused; bump `--rev` to publish a new revision.
+- `--skip-register` skips the graph-registration call for a graph that already
+  exists.
+- Requires an internal account whose org has the Production Control
+  entitlement; other keys get "cannot upload runs to Production Control".
+
 Configuration:
 
 - `ASSETHUB_API_KEY`: optional when a profile was saved with `auth login`.
@@ -79,12 +362,13 @@ is preferred. Use `--all-ready` rather than explicit `--task-id` values when
 preprocessing is enabled, because the generated-image split creates a separate
 production order.
 
-Image generation defaults to the deployed `v1` endpoint. Pass `--api-version v2`
-only when the `v2` image endpoint is available in the target environment.
+Image generation uses the `v2` endpoint with mandatory canvas history.
+`--api-version v1` is rejected; run `assethub capabilities` to check availability.
 
-Part extraction uses the same public names shown in the AssetHub product:
-`V1`, `V1.5 alpha`, `V1.5`, `V2.0 alpha`, and `V2.1 alpha`. Internal agent
-IDs are intentionally not part of the public CLI interface.
+Part extraction uses the same names shown in the AssetHub product: `V1.5`,
+`V2.0 alpha`, `V2.1 alpha`, and the Internal-only `V3.6.1` alias for
+`V3.6.1 Primary Images First`. Retired names are no longer accepted by the CLI.
+Internal agent IDs are intentionally not part of the CLI interface.
 
 The CLI only uses AssetHub's public API surface and is designed so this package
 can be published independently from the private application monorepo.

package/dist/canvas.d.ts

@@ -0,0 +1,27 @@
+import type { Canvas } from '@assethub/api-client';
+type CanvasScope = {
+    stateDir: string;
+    cwd: string;
+    baseUrl: string;
+    ownerId: string;
+};
+type CanvasClient = {
+    v2: {
+        createCanvas: (body: {
+            name: string;
+        }, options: {
+            idempotencyKey: string;
+        }) => Promise<Canvas>;
+        getCanvas: (id: number) => Promise<Canvas>;
+    };
+};
+export declare const writeState: (path: string, value: unknown) => Promise<void>;
+export declare const readState: (path: string) => Promise<unknown | undefined>;
+export declare const saveCanvasSelection: (scope: CanvasScope, canvasId: number) => Promise<void>;
+export declare const resolveCanvasSelection: (options: CanvasScope & {
+    client: CanvasClient;
+    canvasId?: number;
+    create?: boolean;
+}) => Promise<Canvas>;
+export {};
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,sBAAsB,CAAA;AAEhD,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACD,KAAK,YAAY,GAAG;IAClB,EAAE,EAAE;QACF,YAAY,EAAE,CACZ,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,EACpB,OAAO,EAAE;YAAC,cAAc,EAAE,MAAM,CAAA;SAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAA;QACpB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;KAC3C,CAAA;CACF,CAAA;AAED,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,OAAO,OAAO,KACb,OAAO,CAAC,IAAI,CAWd,CAAA;AAED,eAAO,MAAM,SAAS,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAazE,CAAA;AAiBD,eAAO,MAAM,mBAAmB,GAC9B,OAAO,WAAW,EAClB,UAAU,MAAM,KACf,OAAO,CAAC,IAAI,CAOd,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,SAAS,WAAW,GAAG;IACrB,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,KACA,OAAO,CAAC,MAAM,CA8ChB,CAAA"}

package/dist/canvas.js

@@ -0,0 +1,82 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, rename, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+export const writeState = async (path, value) => {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await unlink(temporary).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+    }
+};
+export const readState = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+};
+const scopeHash = async (scope) => createHash('sha256')
+    .update(JSON.stringify([
+    scope.baseUrl.replace(/\/+$/, ''),
+    scope.ownerId,
+    await realpath(scope.cwd),
+]))
+    .digest('hex');
+/** A stable operation identity lets the server deduplicate even a crashed first invocation. */
+const creationId = (hash) => `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+export const saveCanvasSelection = async (scope, canvasId) => {
+    if (!Number.isSafeInteger(canvasId) || canvasId <= 0)
+        throw new Error('Canvas ID must be a positive integer');
+    await writeState(join(scope.stateDir, 'canvases', `${await scopeHash(scope)}.json`), { canvasId });
+};
+export const resolveCanvasSelection = async (options) => {
+    const { client } = options;
+    let canvasId = options.canvasId;
+    const hash = await scopeHash(options);
+    if (canvasId == null) {
+        const stored = await readState(join(options.stateDir, 'canvases', `${hash}.json`));
+        if (stored != null) {
+            if (typeof stored !== 'object' ||
+                !('canvasId' in stored) ||
+                !Number.isSafeInteger(stored.canvasId)) {
+                throw new Error('Invalid saved canvas selection; select one with canvas use <id>');
+            }
+            canvasId = Number(stored.canvasId);
+        }
+    }
+    if (canvasId != null) {
+        if (!Number.isSafeInteger(canvasId) || canvasId <= 0)
+            throw new Error('Canvas ID must be a positive integer');
+        const canvas = await client.v2.getCanvas(canvasId);
+        if (canvas.ownerId !== options.ownerId)
+            throw new Error('Canvas belongs to a different organization');
+        return canvas;
+    }
+    if (options.create === false)
+        throw new Error('No canvas selected; use --canvas <id> or canvas use <id>');
+    // Check local persistence before starting a remote mutation. The same scope
+    // always posts the same name and key, including after a lost response.
+    const directory = join(options.stateDir, 'canvases');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const probe = join(directory, `${hash}.${randomUUID()}.probe`);
+    await writeFile(probe, '', { mode: 0o600, flag: 'wx' });
+    await unlink(probe);
+    const canvas = await client.v2.createCanvas({ name: `CLI ${basename(await realpath(options.cwd))} ${hash.slice(0, 8)}` }, { idempotencyKey: creationId(hash) });
+    if (canvas.ownerId !== options.ownerId)
+        throw new Error('Created canvas belongs to a different organization');
+    await saveCanvasSelection(options, canvas.id);
+    return canvas;
+};

package/dist/canvasAssetImport.d.ts

@@ -0,0 +1,45 @@
+import type { Source } from '@assethub/api-client';
+type DurableSource = Extract<Source, {
+    uploadId: string;
+} | {
+    resourceId: string;
+}>;
+type ImportedAsset = {
+    assetId: string;
+    mediaType: 'image';
+    canvasId: number;
+};
+type ImportClient = {
+    v2: {
+        uploadFile: (input: {
+            file: Blob;
+            fileName: string;
+            mediaType: 'image';
+        }) => Promise<{
+            uploadId?: string;
+        }>;
+        importCanvasAsset: (canvasId: number, input: {
+            source: DurableSource;
+            name?: string;
+        }) => Promise<ImportedAsset>;
+    };
+};
+type ImportOptions = {
+    client: ImportClient;
+    baseUrl: string;
+    ownerId: string;
+    canvasId: number;
+    stateDir: string;
+    filePath?: string;
+    contentType?: string;
+    source?: DurableSource;
+    name?: string;
+};
+/** Keep staging/import receipts separate from paid generation operation state. */
+export declare function importCanvasAssetWithState(options: ImportOptions): Promise<ImportedAsset & {
+    statePath: string;
+    sha256?: string;
+    uploadId?: string;
+}>;
+export {};
+//# sourceMappingURL=canvasAssetImport.d.ts.map

package/dist/canvasAssetImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasAssetImport.d.ts","sourceRoot":"","sources":["../src/canvasAssetImport.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,sBAAsB,CAAA;AAGhD,KAAK,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAAC,CAAA;AAC/E,KAAK,aAAa,GAAG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAA;AAC5E,KAAK,YAAY,GAAG;IAClB,EAAE,EAAE;QACF,UAAU,EAAE,CAAC,KAAK,EAAE;YAClB,IAAI,EAAE,IAAI,CAAA;YACV,QAAQ,EAAE,MAAM,CAAA;YAChB,SAAS,EAAE,OAAO,CAAA;SACnB,KAAK,OAAO,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAC,CAAC,CAAA;QAClC,iBAAiB,EAAE,CACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE;YAAC,MAAM,EAAE,aAAa,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAC,KAC1C,OAAO,CAAC,aAAa,CAAC,CAAA;KAC5B,CAAA;CACF,CAAA;AAaD,KAAK,aAAa,GAAG;IACnB,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAcD,kFAAkF;AAClF,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,aAAa,GACrB,OAAO,CACR,aAAa,GAAG;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAC,CACxE,CAwJA"}

package/dist/canvasAssetImport.js

@@ -0,0 +1,154 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { readState, writeState } from './canvas.js';
+const imageContentTypes = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.avif': 'image/avif',
+    '.bmp': 'image/bmp',
+    '.tif': 'image/tiff',
+    '.tiff': 'image/tiff',
+};
+/** Keep staging/import receipts separate from paid generation operation state. */
+export async function importCanvasAssetWithState(options) {
+    if (!Number.isSafeInteger(options.canvasId) ||
+        options.canvasId <= 0 ||
+        !options.ownerId)
+        throw new Error('An owned canvas is required for image import');
+    if (Boolean(options.filePath) === Boolean(options.source))
+        throw new Error('Provide exactly one file, upload ID, or resource ID');
+    const name = options.name?.trim();
+    if (name !== undefined && (!name || name.length > 200))
+        throw new Error('Import name must be between 1 and 200 characters');
+    const bytes = options.filePath
+        ? await readFile(resolve(options.filePath))
+        : undefined;
+    const sha256 = bytes
+        ? createHash('sha256').update(bytes).digest('hex')
+        : undefined;
+    const sourceIdentity = sha256
+        ? `sha256:${sha256}`
+        : options.source?.uploadId
+            ? `upload:${options.source.uploadId}`
+            : options.source?.resourceId
+                ? `resource:${options.source.resourceId}`
+                : undefined;
+    if (!sourceIdentity)
+        throw new Error('Import source ID is required');
+    const scope = {
+        baseUrl: options.baseUrl.replace(/\/+$/, ''),
+        ownerId: options.ownerId,
+        canvasId: options.canvasId,
+        sourceIdentity,
+    };
+    const key = createHash('sha256').update(JSON.stringify(scope)).digest('hex');
+    const statePath = join(options.stateDir, 'canvas-imports', `${key}.json`);
+    const readReceipt = async () => {
+        const value = await readState(statePath);
+        if (value === undefined)
+            return undefined;
+        if (!value ||
+            typeof value !== 'object' ||
+            !('schemaVersion' in value) ||
+            value.schemaVersion !== 'assethub.canvas-import.v1' ||
+            !('baseUrl' in value) ||
+            value.baseUrl !== scope.baseUrl ||
+            !('ownerId' in value) ||
+            value.ownerId !== scope.ownerId ||
+            !('canvasId' in value) ||
+            value.canvasId !== scope.canvasId ||
+            !('sourceIdentity' in value) ||
+            value.sourceIdentity !== sourceIdentity)
+            throw new Error(`Invalid or differently scoped import receipt: ${statePath}`);
+        const saved = value;
+        if ((saved.uploadId !== undefined &&
+            (typeof saved.uploadId !== 'string' || !saved.uploadId)) ||
+            (saved.resourceId !== undefined &&
+                (typeof saved.resourceId !== 'string' || !saved.resourceId)) ||
+            (sha256 !== undefined && saved.sha256 !== sha256))
+            throw new Error(`Invalid import source in receipt: ${statePath}`);
+        if (name !== undefined && saved.name !== name)
+            throw new Error(`This source has an import receipt with a different name. Reuse its original name: ${statePath}`);
+        return saved;
+    };
+    let saved = await readReceipt();
+    if (!saved?.uploadId && !saved?.resourceId) {
+        await mkdir(dirname(statePath), { recursive: true, mode: 0o700 });
+        const lockPath = `${statePath}.upload-lock`;
+        const lock = await open(lockPath, 'wx', 0o600).catch(error => {
+            if (error &&
+                typeof error === 'object' &&
+                'code' in error &&
+                error.code === 'EEXIST')
+                throw new Error(`An upload for this source is already in progress. Retry the same command after it finishes. If its process was terminated, verify the PID in ${lockPath} is stopped before removing that lock.`);
+            throw error;
+        });
+        try {
+            await lock.writeFile(JSON.stringify({ pid: process.pid }));
+            // Another process may have completed its upload between our initial read and lock acquisition.
+            saved = await readReceipt();
+            if (!saved?.uploadId && !saved?.resourceId) {
+                saved ??= {
+                    schemaVersion: 'assethub.canvas-import.v1',
+                    ...scope,
+                    ...(sha256 ? { sha256 } : {}),
+                    ...(name === undefined ? {} : { name }),
+                };
+                await writeState(statePath, saved);
+                if (bytes && options.filePath) {
+                    const uploaded = await options.client.v2.uploadFile({
+                        file: new Blob([bytes], {
+                            type: options.contentType ??
+                                imageContentTypes[extname(options.filePath).toLowerCase()] ??
+                                'application/octet-stream',
+                        }),
+                        fileName: basename(options.filePath),
+                        mediaType: 'image',
+                    });
+                    if (!uploaded.uploadId)
+                        throw new Error('Server did not return a durable upload ID');
+                    saved.uploadId = uploaded.uploadId;
+                }
+                else if (options.source?.uploadId)
+                    saved.uploadId = options.source.uploadId;
+                else if (options.source?.resourceId)
+                    saved.resourceId = options.source.resourceId;
+                // Never call durable import before its upload identity has been persisted.
+                await writeState(statePath, saved);
+            }
+        }
+        finally {
+            await lock.close();
+            await unlink(lockPath);
+        }
+    }
+    const source = saved?.uploadId
+        ? { uploadId: saved.uploadId }
+        : saved?.resourceId
+            ? { resourceId: saved.resourceId }
+            : (() => {
+                throw new Error('Import receipt has no durable source');
+            })();
+    // Revalidate on the server even after a successful cached result. Promotion
+    // recognizes this same upload after staging cleanup and never creates a new asset.
+    const result = await options.client.v2.importCanvasAsset(options.canvasId, {
+        source,
+        name: saved.name,
+    });
+    if (result.canvasId !== options.canvasId ||
+        result.mediaType !== 'image' ||
+        !result.assetId ||
+        (saved.result && saved.result.assetId !== result.assetId))
+        throw new Error(`Server returned an inconsistent imported asset; inspect ${statePath}`);
+    await writeState(statePath, { ...saved, result });
+    return {
+        ...result,
+        statePath,
+        ...(sha256 ? { sha256 } : {}),
+        ...(saved.uploadId ? { uploadId: saved.uploadId } : {}),
+    };
+}

package/dist/canvasComparison.d.ts

@@ -0,0 +1,21 @@
+import type { AssetHubClient } from '@assethub/api-client';
+/** A portable review artifact; downloading uses signed URLs, never the API key. */
+export declare function writeCanvasComparison(input: {
+    client: AssetHubClient;
+    canvasId: number;
+    sourceId: string;
+    assetId: string;
+    out: string;
+    title?: string;
+}): Promise<{
+    canvasId: number;
+    canvasUrl: string;
+    reviewStatus: string;
+    images: {
+        assetId: string;
+        sha256: string;
+    }[];
+    path: string;
+    provenancePath: string;
+}>;
+//# sourceMappingURL=canvasComparison.d.ts.map

package/dist/canvasComparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasComparison.d.ts","sourceRoot":"","sources":["../src/canvasComparison.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAA;AAWxD,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;;;;;;;;;;GAuDA"}