@12ui/design 0.2.0

package/README.md

@@ -0,0 +1,484 @@
+# @12ui/design
+
+`@12ui/design` is the canonical 12UI CLI, SDK, MCP server, and agent-skill
+package. The `12ui` binary stays stable while package imports and installation
+use the new name.
+
+Install with Node on macOS, Linux, or Windows:
+
+```bash
+npx -y @12ui/design skill install
+```
+
+Or use the genuinely npm-free macOS/Linux installer:
+
+```bash
+curl -fsSL https://12ui.com/install.sh | sh
+```
+
+Both paths pin the exact CLI version, install `design`, `design-search`, and
+`design-convert` into every detected Codex and Claude Code installation, and
+open the 12UI device-approval page. The resulting user-owned credential has
+`design.convert` and `design.corpus.retrieve`, is verified before use, and is
+stored mode-0600 at `$XDG_CONFIG_HOME/12ui/credentials.json` or
+`~/.config/12ui/credentials.json`.
+
+An already verified credential is reused. The installer migrates the legacy
+`~/.config/just-every/12ui/credentials.json` location; two conflicting files
+fail closed. Existing unknown or locally modified skills also fail closed
+unless `--force` is explicit. Use `--skill design-search` (or either other
+skill name) to install one skill instead of the complete bundle.
+
+## Three visual interface skills
+
+- `design` routes UI, web, and mobile work. Finished screenshots go directly
+  to conversion, tiny edits stay code-only, and rough briefs retrieve exactly
+  four references, generate four candidates conditioned on all four, select
+  one, convert only the winner, integrate it, and verify the real surface.
+- `design-search` returns a ranked, diverse set of real Design Corpus
+  references while preserving endpoint order and metrics.
+- `design-convert` turns a finished PNG, JPEG, or WebP into LayerDoc and any
+  supported responsive, fixed, project, or document export.
+
+The design workflow exists because code-first agents often converge on safe,
+generic visual defaults. Corpus-conditioned image generation expands the
+design space and introduces personality; converting the selected image then
+preserves that direction with near-pixel-perfect fidelity much faster than
+manual recreation.
+
+```bash
+12ui skill status --json
+12ui auth status
+12ui corpus inspire --query-file ./brief.txt --out-dir ./references --count 4
+12ui image generate --prompt-file ./candidate-1.txt \
+  --reference-1 ./references/01.webp \
+  --reference-2 ./references/02.webp \
+  --reference-3 ./references/03.webp \
+  --reference-4 ./references/04.webp \
+  --out ./candidate-1.png \
+  --aspect landscape \
+  --project-root . \
+  --provider auto \
+  --idempotency-key product-candidate-1
+12ui export <base-layerdoc-conversion-id> \
+  --output html,pdf,psd,pptx,sketch,web_project \
+  --out-dir ./exports \
+  --web-profile ./web-profile.json \
+  --idempotency-key product-exports-v1
+```
+
+`image generate` resolves one provider before dispatch: authenticated Codex,
+then `OPENAI_API_KEY` from the process or exactly `<project-root>/.env`. It
+refuses a Git-tracked `.env`, never stores or prints the key, persists attempt
+evidence, and never switches providers after dispatch. Choose `--aspect`
+explicitly for the target interface; it defaults to `landscape` for
+compatibility.
+
+`export` downloads one successful base LayerDoc once and dispatches the chosen
+formats in parallel. Project exports require exact web/native profiles; image
+extraction is not repeated.
+
+## Design Corpus retrieval
+
+`TwelveUiCorpusClient` uses an API key with the `design.corpus.retrieve` scope.
+Use `mode: 'record'` for product allocations so exposure history can prevent
+the same references from dominating later runs. Use `mode: 'ignore'` only for
+operator diagnostics and search inspection.
+
+```ts
+import { TwelveUiCorpusClient } from '@12ui/design';
+
+const corpus = new TwelveUiCorpusClient({
+  origin: process.env.TWELVE_UI_ORIGIN ?? 'https://12ui.com',
+  apiKey: process.env.TWELVE_UI_API_KEY!,
+});
+
+const status = await corpus.status();
+const retrieved = await corpus.retrieve({
+  scope: 'r-track',
+  queries: [{
+    id: 'home',
+    brief: 'Editorial architecture home page',
+    direction: 'warm materiality and asymmetric typography',
+    targetCount: 6,
+  }],
+  context: {
+    mode: 'record',
+    purpose: 'run',
+    exposureScope: 'project:example',
+    allocationKey: 'example-home-v1',
+  },
+});
+
+const first = retrieved.allocations[0]!.results[0]!;
+const metadata = await corpus.reference(first.referenceId);
+const image = await corpus.download(first.referenceId, 'ref');
+```
+
+The client sends the allocation key as the idempotency key. The API also
+supports `logo-track`, batched queries, exclusions, preselected references, and
+minimum quality thresholds. See
+[`docs/corpus-v1.openapi.yaml`](https://github.com/just-every/12ui/blob/main/docs/corpus-v1.openapi.yaml).
+
+For agent workflows that need four fresh, budget-metered inspiration images,
+the CLI calls `/api/v1/corpus/inspire`, downloads the full reference images in
+parallel, verifies each WebP, and writes a content-hashed manifest:
+
+```bash
+node "$TWELVE_UI_REPO/packages/12ui/dist/cli.js" corpus inspire \
+  --query-file ./brief.txt \
+  --count 4 \
+  --wildness 0.6 \
+  --idempotency-key design-run:home-v1 \
+  --out-dir ./references
+```
+
+The output directory must not already exist. Before dispatch, the CLI writes
+`inspire-attempt.json` with the exact request and stable idempotency key. A
+successful run also contains `manifest.json`, `inspire-evidence.json` with the
+exact upstream response, four numbered reference files, and a durable digest
+receipt for each image under `.reference-receipts/`. If the HTTP result is
+ambiguous or one or more image downloads fail, finish the same allocation
+without a second paid embedding:
+
+```bash
+node "$TWELVE_UI_REPO/packages/12ui/dist/cli.js" corpus resume \
+  --out-dir ./references \
+  --origin https://12ui.com
+```
+
+`corpus resume` reuses the attempt's idempotency key. The Worker either returns
+the original stored response or reports the still-pending request; it never
+dispatches a second embedding for that identity. Reusing a key with a different
+validated request returns `409 idempotency_conflict`. A reference already on
+disk is accepted only when its bytes match its exclusive digest receipt.
+
+The CLI deliberately does not accept a free-form `--kind`: an unverified value
+can consume the metered request while producing an empty set. Use the SDK's
+`filters.kind` only when an integration has obtained and verified the exact
+corpus kind value.
+
+## Multi-page packages
+
+`TwelveUiConversionPackageClient` accepts the version-1 package manifest plus
+explicit screenshot, LayerDoc, and raster-asset parts. It polls one durable
+parent operation while the service converts missing viewports and exports final
+pages in parallel.
+
+```ts
+import { TwelveUiConversionPackageClient } from '@12ui/design';
+
+const packages = new TwelveUiConversionPackageClient({
+  origin: process.env.TWELVE_UI_ORIGIN ?? 'https://12ui.com',
+  apiKey: process.env.TWELVE_UI_API_KEY!,
+});
+
+const created = await packages.createPackage({
+  manifest: {
+    version: 1,
+    output: 'layerdoc',
+    pages: [{
+      id: 'home',
+      ordinal: 0,
+      viewports: [{ id: 'hero', ordinal: 0, screenshot_part: 'home-hero' }],
+    }],
+  },
+  screenshots: [{
+    partId: 'home-hero',
+    bytes: screenshotBytes,
+    mediaType: 'image/png',
+  }],
+});
+
+const completed = created.status === 'succeeded'
+  ? created
+  : await packages.waitForPackage(created.id);
+const home = await packages.downloadPage(completed, 'home');
+```
+
+See [`docs/CONVERSION_PACKAGES.md`](https://github.com/just-every/12ui/blob/main/docs/CONVERSION_PACKAGES.md) for the
+strict manifest, asset mapping, normalization, page-join, and limit contract.
+
+## CLI
+
+```bash
+export TWELVE_UI_API_KEY=your-key
+12ui convert ./screen.png --output layerdoc --out ./screen.layerdoc.json
+12ui convert ./screen.png --output html --model pro --width 1440 --out ./screen.html --timeout-ms 7200000
+12ui convert ./screen.layerdoc.json --output html --out ./screen.html --idempotency-key screen-html-v1
+12ui convert ./screen.layerdoc.json --output pptx --out ./screen.pptx --idempotency-key screen-pptx-v1
+12ui convert ./screen.layerdoc.json --output web_project --profile ./react-tailwind.json --out ./screen-react.zip
+12ui convert ./screen.layerdoc.json --output app_project --profile '{"version":1,"framework":"swiftui","styling":"native","language":"swift","packaging":"project"}' --out ./screen-ios.zip
+12ui resume conversion-id --output layerdoc --out ./screen.layerdoc.json
+```
+
+Each conversion also writes a verified `<out>.assets/manifest.json` plus every
+signed raster artifact beside the requested result. Set `TWELVE_UI_ORIGIN` to
+override `https://12ui.com`; waits default to the operation expiry and can be
+bounded explicitly with `--timeout-ms`.
+
+To retry an ambiguous create request safely, reuse the same explicit
+`--idempotency-key`. When it is omitted, the client generates a new UUID.
+
+Image conversions accept `--model fast|standard|pro`; omission selects
+`standard`. In `layerdoc-worker-v148`, Fast, Standard, and Pro all use
+`gpt-5.6-terra-low` for primary extraction. Fast retains color-guided
+deterministic inpainting, source-grounded flat-border cutouts, and 1x source crops without
+secondary metadata refinement, generative cleanup, provider background
+removal, or upscaling. Standard has no secondary metadata refinement and uses
+one atomic GPT Image 2 result for each opaque clean target, with Pixelcut-first
+alpha isolation and Bria admitted only after a durable hard-invalid or
+reconciled terminal Pixelcut failure. Standard performs no Luna candidate
+review. Pro retains a separate `gpt-5.6-terra-low` metadata-refinement call, a
+three-sample atomic opaque-clean portfolio with one comparative Luna review,
+and the complete revision-frozen FAL alpha portfolio. GPT Image 2 is opaque-only.
+Provider-routed cutouts keep enhanced upscaling; accepted deterministic Fast
+cutouts are resized locally. The option is not accepted for LayerDoc input
+because downstream compilation is deterministic.
+
+Use `--width <px>` to set the native output canvas width. The CLI resizes image
+input proportionally before upload, upscaling or downscaling as needed. The
+selected model may analyze a smaller internal raster without changing that
+authored width; do not switch to Pro merely because the native canvas exceeds
+Standard's analysis edge. For example, an 800x600 source with `--width 1000`
+becomes a 1000x750 conversion canvas, and a 1536x1024 Standard source remains a
+1536x1024 native canvas while analysis is bounded to 1500x1000. `--width 390`
+turns a 1170 px-wide 3x phone capture into a 390 px conversion canvas. The
+option is not accepted for LayerDoc input or `resume`.
+
+LayerDoc input accepts the public v2 JSON downloaded from the API. Its signed
+raster references must still be valid and must belong to the same authenticated
+account. The service resolves those owned artifacts directly; it does not fetch
+arbitrary remote URLs. LayerDoc input produces `layerdoc`, `html`, `svg`, `png`, `jpg`, `webp`, `pdf`, `psd`,
+`pptx`, `sketch`, `web_project`, or `app_project`. Project outputs require
+`--profile <json|file>`; the CLI also accepts `--profile @file.json`.
+
+## LayerDoc to downstream formats
+
+The raw LayerDoc representation can be submitted directly to a second
+conversion. This makes it possible to edit the document's text, geometry, or
+style before compiling responsive HTML or a fixed export while retaining its
+signed asset refs:
+
+```ts
+import fs from 'node:fs';
+import { TwelveUiConversionClient } from '@12ui/design';
+
+const client = new TwelveUiConversionClient({
+  origin: process.env.TWELVE_UI_ORIGIN ?? 'https://12ui.com',
+  apiKey: process.env.TWELVE_UI_API_KEY!,
+});
+
+const created = await client.createConversion({
+  layerdoc: new Uint8Array(await fs.promises.readFile('./screen.layerdoc.json')),
+  filename: 'screen.layerdoc.json',
+  output: 'html',
+});
+
+const completed = created.status === 'succeeded'
+  ? created
+  : await client.waitForConversion(created.id, { expiresAt: created.expires_at });
+const html = await client.downloadResult(completed.id, 'html');
+await fs.promises.writeFile('./screen.html', html.bytes);
+```
+
+For generated responsive layouts, derive from the successful image-to-LayerDoc
+operation instead of uploading the image again:
+
+```ts
+const responsive = await client.createConversion({
+  sourceConversionId: imageToLayerDoc.id,
+  output: 'html',
+  responsiveQuality: 'pro', // standard | pro
+});
+```
+
+This authenticated path reuses the canonical LayerDoc and raster assets from
+`imageToLayerDoc`, consumes export quota, and starts directly at responsive
+reference generation. The source conversion must still be retained and must
+have been produced by the current pipeline revision.
+
+While the operation is queued or running, poll it normally and read
+`responsive_preview`. Its frames are returned in mobile, tablet, then compact
+desktop plan order. Each frame moves through `waiting`, `generating`,
+`generated`, `extracting`, `binding`, and `complete`; its signed `artifact`
+appears immediately after the real generated reference PNG is durably
+registered. `completed` and `total` count reference, extraction, and binding as
+three durable steps per admitted anchor, while `progress.percent` remains the
+overall conversion progress for a single progress bar.
+
+Project output uses the same client method and returns a deterministic ZIP:
+
+```ts
+const createdProject = await client.createConversion({
+  layerdoc: new Uint8Array(await fs.promises.readFile('./screen.layerdoc.json')),
+  filename: 'screen.layerdoc.json',
+  output: 'web_project',
+  profile: {
+    version: 1,
+    framework: 'react',
+    styling: 'tailwind',
+    language: 'typescript',
+    packaging: 'project',
+  },
+});
+
+const projectOperation = createdProject.status === 'succeeded'
+  ? createdProject
+  : await client.waitForConversion(createdProject.id, {
+      expiresAt: createdProject.expires_at,
+    });
+const project = await client.downloadResult(projectOperation.id, 'web_project');
+await fs.promises.writeFile('./screen-react.zip', project.bytes);
+```
+
+The complete version-1 capability matrix is documented in
+[`docs/EXPORT_FORMATS.md`](https://github.com/just-every/12ui/blob/main/docs/EXPORT_FORMATS.md). Unsupported framework,
+styling, language, or packaging combinations fail before upload; the client
+does not substitute a nearby target.
+
+The 10 web framework slugs are `html`, `react`, `next`, `vue`, `nuxt`, `svelte`,
+`sveltekit`, `angular`, `astro`, and `lit`. The 9 app framework slugs are `expo`,
+`react_native`, `flutter`, `ionic_capacitor`, `swiftui`, `uikit`,
+`jetpack_compose`, `android_views`, and `compose_multiplatform`. Import
+`WEB_PROJECT_CAPABILITIES` and `APP_PROJECT_CAPABILITIES` from this package to
+enumerate the exact styling, language, and packaging cross-products at runtime.
+For web output, `component` is reusable component source, `page` is a route/page
+entrypoint, and `project` is a runnable scaffold. For app output, `screen` is
+integration-ready screen source for an existing app, while `project` adds the
+runnable scaffold and build configuration.
+
+## Hosted `/convert` two-phase workflow
+
+The Node client above remains API-key authenticated and may request any valid
+image output directly. The free hosted web page uses the same HTTP resources
+with an intentionally narrower contract:
+
+1. Create one image conversion with `output: "layerdoc"`.
+2. Poll the operation and replace the interactive preview only when
+   `operation.preview.revision` increases.
+3. Fetch the final LayerDoc representation after the source succeeds.
+4. Keep that hydrated JSON in memory and create independent LayerDoc-input jobs
+   for `html`, `svg`, `png`, `jpg`, `webp`, `pdf`, `psd`, `pptx`, `sketch`, `web_project`, and
+   `app_project`. Different formats and project profiles can
+   run in parallel; a repeated completed format should download the cached
+   representation rather than create another run.
+
+No special export endpoint is involved. The source conversion remains the web
+session root, and each export is an ordinary `POST /api/v1/convert` followed by
+polling `GET /api/v1/convert/:id`. LayerDoc input is accepted only after its
+source run has succeeded because the Worker verifies its signed artifacts,
+expiry, and ownership before importing them.
+
+Anonymous hosted-page requests send `X-12UI-Public-Preview: 1` and the same
+browser-generated `X-12UI-Public-Visitor` value. Public image creation also
+includes `cf-turnstile-response` in multipart form data; its verified action is
+`12ui_convert_image`. Public quotas are 5 Fast, 2 Standard, no Pro, and 20
+exports per salted IP hash per UTC day. Signed-in and API accounts receive 50
+Fast, 20 Standard, 2 Pro, and 200 exports per stable account id and UTC day.
+`GET /api/v1/convert/quota` returns all buckets; successful POST responses
+identify the admitted bucket and return its limit and remaining count. Daily
+exhaustion returns `429` with `Retry-After`.
+
+All runs are sponsored and do not check or debit Login credits. Provider,
+model, request-id, reservation, actual-cost, principal-tier, and account-id
+records are retained in durable ledgers independent of expiring conversion
+artifacts. Public headers are for the trusted anonymous preview; CLI and MCP
+consumers should keep using a Login-issued API key.
+
+Running LayerDoc operations may include an immutable `preview`: `structure`
+contains the final layer tree and prepared source, while `standard` adds 1×
+crops and cleaned plates. `result` remains reserved for the final enhanced,
+manifest-last publication. `progress.active` reports durable completed/total
+counts for each materialization lane.
+
+## Progressive Node consumer
+
+`waitForConversion` intentionally returns only the terminal operation. A
+consumer that wants live progress or previews should poll `getConversion` and
+apply every operation snapshot:
+
+```ts
+import fs from 'node:fs';
+import { TwelveUiConversionClient } from '@12ui/design';
+
+declare function renderLayerDoc(document: unknown): void;
+
+const client = new TwelveUiConversionClient({
+  origin: process.env.TWELVE_UI_ORIGIN ?? 'https://12ui.com',
+  apiKey: process.env.TWELVE_UI_API_KEY!,
+});
+
+const created = await client.createConversion({
+  bytes: new Uint8Array(await fs.promises.readFile('./screen.png')),
+  filename: 'screen.png',
+  mediaType: 'image/png',
+  output: 'layerdoc',
+  model: 'standard',
+});
+
+let operation = created;
+let displayedRevision = 0;
+
+while (operation.status === 'queued' || operation.status === 'running') {
+  const progress = operation.progress;
+  if (progress) {
+    console.log(progress.percent, progress.stage, progress.milestone);
+    for (const lane of progress.active ?? []) {
+      console.log(lane.kind, lane.completed, lane.total, lane.status);
+    }
+  }
+
+  if (operation.preview && operation.preview.revision > displayedRevision) {
+    displayedRevision = operation.preview.revision;
+    renderLayerDoc(operation.preview.document);
+    // operation.preview.artifacts contain signed hrefs that are usable now.
+  }
+
+  await new Promise((resolve) => setTimeout(resolve, 1_000));
+  operation = await client.getConversion(operation.id);
+}
+
+if (operation.status !== 'succeeded' || operation.result?.kind !== 'layerdoc') {
+  throw new Error(operation.error?.detail ?? `Conversion ${operation.status}`);
+}
+
+// The terminal result is authoritative and replaces any displayed preview.
+renderLayerDoc(operation.result.document);
+```
+
+Raw HTTP consumers should use `Accept: application/json` while polling and
+respect the response's `Retry-After` header (currently one second). `Prefer:
+wait=20` only allows the create request to wait for an early result; it is not
+a streaming connection. There is no SSE or WebSocket contract.
+
+Progress and preview rules:
+
+- `progress.percent` is the weighted server calculation; do not derive a
+  percentage from the stage name.
+- `progress.active` is optional and image-specific. Do not assume every lane
+  is present or that lane order is fixed.
+- `milestone` is `structure_ready` or `standard_ready` once that preview is
+  available.
+- Previews currently apply to `output=layerdoc`. Downstream HTML and fixed
+  export operations still expose progress, but publish only their terminal result.
+- Preview revision 1 is `quality: "structure"`; revision 2 is
+  `quality: "standard"`. Treat revisions as immutable snapshots.
+- A preview artifact id is never repointed to different bytes. Signed `href`
+  values expire with the operation; re-read the operation to refresh URLs.
+- On `succeeded`, use `result` as authoritative. On `failed` or `expired`, use
+  `error` and discard any displayed preview as a non-terminal aid.
+
+## MCP
+
+```bash
+12ui mcp
+```
+
+The server exposes one tool, `design.convert`, backed by the same
+`POST /api/v1/convert` and `GET /api/v1/convert/:id` contract as the CLI. Pass
+`imagePath` for PNG/JPEG/WebP input or `layerdocPath` for public LayerDoc v2
+JSON input; `layerdocPath` accepts every downstream output. Pass the exact
+`profile` object for `web_project` or `app_project`. Set the optional
+`idempotencyKey` when an ambiguous create may need to be retried with the same
+stable key; otherwise the client generates a new UUID.

package/dist/artifact-materializer.d.ts

@@ -0,0 +1,17 @@
+import { TwelveUiConversionClient, type ConversionOperation } from './conversion-client.js';
+export type MaterializedArtifact = {
+    id: string;
+    role: string;
+    mediaType: string;
+    sha256: string;
+    sourceHref: string;
+    localPath: string;
+};
+export type MaterializedArtifactManifest = {
+    conversionId: string;
+    operationExpiresAt: string;
+    manifestFile: string;
+    artifacts: MaterializedArtifact[];
+};
+export declare const materializeConversionArtifacts: (client: TwelveUiConversionClient, operation: ConversionOperation, resultFile: string) => Promise<MaterializedArtifactManifest>;
+//# sourceMappingURL=artifact-materializer.d.ts.map

package/dist/artifact-materializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-materializer.d.ts","sourceRoot":"","sources":["../src/artifact-materializer.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EAExB,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,oBAAoB,EAAE,CAAC;CACnC,CAAC;AA6BF,eAAO,MAAM,8BAA8B,GACzC,QAAQ,wBAAwB,EAChC,WAAW,mBAAmB,EAC9B,YAAY,MAAM,KACjB,OAAO,CAAC,4BAA4B,CA2BtC,CAAC"}

package/dist/artifact-materializer.js

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const extensionForMediaType = (mediaType) => {
+    const normalized = mediaType.toLowerCase().split(';', 1)[0]?.trim();
+    if (normalized === 'image/png')
+        return '.png';
+    if (normalized === 'image/jpeg')
+        return '.jpg';
+    if (normalized === 'image/webp')
+        return '.webp';
+    if (normalized === 'application/json')
+        return '.json';
+    if (normalized === 'text/html')
+        return '.html';
+    if (normalized === 'image/svg+xml')
+        return '.svg';
+    if (normalized === 'application/pdf')
+        return '.pdf';
+    if (normalized === 'image/vnd.adobe.photoshop')
+        return '.psd';
+    if (normalized === 'application/vnd.openxmlformats-officedocument.presentationml.presentation')
+        return '.pptx';
+    if (normalized === 'application/zip')
+        return '.sketch';
+    return '.bin';
+};
+const safeArtifactName = (artifact) => {
+    const stem = artifact.id.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'artifact';
+    return `${stem}-${artifact.sha256.slice(0, 12).toLowerCase()}${extensionForMediaType(artifact.media_type)}`;
+};
+const assertDigest = (artifact, bytes) => {
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== artifact.sha256.toLowerCase()) {
+        throw new Error(`Conversion artifact ${artifact.id} failed SHA-256 verification`);
+    }
+};
+export const materializeConversionArtifacts = async (client, operation, resultFile) => {
+    const artifacts = operation.result?.artifacts ?? [];
+    const directory = `${resultFile}.assets`;
+    await mkdir(directory, { recursive: true });
+    const materialized = await Promise.all(artifacts.map(async (artifact) => {
+        const downloaded = await client.downloadArtifact(artifact);
+        assertDigest(artifact, downloaded.bytes);
+        const localPath = path.join(directory, safeArtifactName(artifact));
+        await writeFile(localPath, downloaded.bytes);
+        return {
+            id: artifact.id,
+            role: artifact.role,
+            mediaType: downloaded.mediaType,
+            sha256: artifact.sha256,
+            sourceHref: artifact.href,
+            localPath,
+        };
+    }));
+    const manifestFile = path.join(directory, 'manifest.json');
+    const manifest = {
+        conversionId: operation.id,
+        operationExpiresAt: operation.expires_at,
+        manifestFile,
+        artifacts: materialized,
+    };
+    await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    return manifest;
+};
+//# sourceMappingURL=artifact-materializer.js.map

package/dist/artifact-materializer.js.map

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

package/dist/cli-arguments.d.ts

@@ -0,0 +1,8 @@
+export type CliFlags = Record<string, string | true>;
+export declare const parseCliArguments: (argv: string[]) => {
+    command: string[];
+    flags: CliFlags;
+};
+export declare const stringFlag: (flags: CliFlags, name: string) => string | undefined;
+export declare const booleanFlag: (flags: CliFlags, name: string) => boolean;
+//# sourceMappingURL=cli-arguments.d.ts.map

package/dist/cli-arguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-arguments.d.ts","sourceRoot":"","sources":["../src/cli-arguments.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAWrD,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EAAE,KACb;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAqBtC,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,QAAQ,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAGnE,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,QAAQ,EAAE,MAAM,MAAM,KAAG,OAA+B,CAAC"}

package/dist/cli-arguments.js

@@ -0,0 +1,39 @@
+const booleanFlags = new Set([
+    'detach',
+    'force',
+    'help',
+    'json',
+    'skip-auth',
+    'version',
+]);
+export const parseCliArguments = (argv) => {
+    const command = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (!value?.startsWith('--')) {
+            if (value)
+                command.push(value);
+            continue;
+        }
+        const name = value.slice(2);
+        if (!name)
+            throw new Error('Invalid empty flag');
+        if (booleanFlags.has(name)) {
+            flags[name] = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next || next.startsWith('--'))
+            throw new Error(`--${name} requires a value`);
+        flags[name] = next;
+        index += 1;
+    }
+    return { command, flags };
+};
+export const stringFlag = (flags, name) => {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+};
+export const booleanFlag = (flags, name) => flags[name] === true;
+//# sourceMappingURL=cli-arguments.js.map

package/dist/cli-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-arguments.js","sourceRoot":"","sources":["../src/cli-arguments.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;IAC3B,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,WAAW;IACX,SAAS;CACV,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAc,EAC0B,EAAE;IAC1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,IAAI,KAAK;gBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC/B,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACjD,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,KAAK,IAAI,mBAAmB,CAAC,CAAC;QAClF,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACnB,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAe,EAAE,IAAY,EAAsB,EAAE;IAC9E,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAe,EAAE,IAAY,EAAW,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC"}

package/dist/cli-auth-command.d.ts

@@ -0,0 +1,3 @@
+import { type CliFlags } from './cli-arguments.js';
+export declare const runAuthCommand: (action: string | undefined, flags: CliFlags) => Promise<void>;
+//# sourceMappingURL=cli-auth-command.d.ts.map

package/dist/cli-auth-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-auth-command.d.ts","sourceRoot":"","sources":["../src/cli-auth-command.ts"],"names":[],"mappings":"AAMA,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAgD5E,eAAO,MAAM,cAAc,GACzB,QAAQ,MAAM,GAAG,SAAS,EAC1B,OAAO,QAAQ,KACd,OAAO,CAAC,IAAI,CA+Dd,CAAC"}