@formigio/fazemos-cli 0.10.64 → 0.10.67

package/dist/lib/assetHash.d.ts

@@ -0,0 +1,39 @@
+/**
+ * F54 — Streaming SHA-256 hash for files of any size.
+ *
+ * AC-F54-13: whole-object SHA-256 computed client-side; broker key matches.
+ * Niko F-2: presigned PUT binds x-amz-checksum-sha256 (base64 of raw SHA-256
+ * bytes); this module returns both hex and base64 so the caller can pass hex
+ * to the API (content_hash, no prefix) and base64 to S3 (checksum header).
+ *
+ * Files are streamed — no full-file buffering — so large files work within
+ * reasonable memory bounds. The resulting hash covers the entire file in one
+ * pass; this is the "whole-object SHA-256" required by AC-F54-13.
+ */
+export interface FileHashResult {
+    /** 64-char lowercase hex — pass to API as content_hash (no sha256: prefix) */
+    hex: string;
+    /** Base64-encoded SHA-256 bytes — pass as x-amz-checksum-sha256 header to S3 */
+    base64: string;
+    /** File size in bytes — pass to API as size_bytes and to S3 as content-length */
+    sizeBytes: number;
+}
+/**
+ * Stream-hash a file with SHA-256 in a single pass.
+ * Returns hex, base64 digest, and file size.
+ */
+export declare function hashFile(filePath: string): Promise<FileHashResult>;
+/**
+ * Hash an in-memory Buffer with SHA-256.
+ * Used for verifying downloaded bytes (fazemos asset get).
+ */
+export declare function hashBuffer(buf: Buffer): {
+    hex: string;
+    base64: string;
+};
+/**
+ * Convert a 64-char raw hex string to base64.
+ * Convenience wrapper for assembling the x-amz-checksum-sha256 value from a
+ * hex content_hash that was returned by the API or read from a pointer file.
+ */
+export declare function hexToBase64(hex: string): string;

package/dist/lib/assetHash.js

@@ -0,0 +1,57 @@
+/**
+ * F54 — Streaming SHA-256 hash for files of any size.
+ *
+ * AC-F54-13: whole-object SHA-256 computed client-side; broker key matches.
+ * Niko F-2: presigned PUT binds x-amz-checksum-sha256 (base64 of raw SHA-256
+ * bytes); this module returns both hex and base64 so the caller can pass hex
+ * to the API (content_hash, no prefix) and base64 to S3 (checksum header).
+ *
+ * Files are streamed — no full-file buffering — so large files work within
+ * reasonable memory bounds. The resulting hash covers the entire file in one
+ * pass; this is the "whole-object SHA-256" required by AC-F54-13.
+ */
+import { createHash } from 'crypto';
+import { createReadStream, statSync } from 'fs';
+/**
+ * Stream-hash a file with SHA-256 in a single pass.
+ * Returns hex, base64 digest, and file size.
+ */
+export function hashFile(filePath) {
+    const sizeBytes = statSync(filePath).size;
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => {
+            hash.update(chunk);
+        });
+        stream.on('end', () => {
+            const digest = hash.digest();
+            resolve({
+                hex: digest.toString('hex'),
+                base64: digest.toString('base64'),
+                sizeBytes,
+            });
+        });
+        stream.on('error', reject);
+    });
+}
+/**
+ * Hash an in-memory Buffer with SHA-256.
+ * Used for verifying downloaded bytes (fazemos asset get).
+ */
+export function hashBuffer(buf) {
+    const digest = createHash('sha256').update(buf).digest();
+    return {
+        hex: digest.toString('hex'),
+        base64: digest.toString('base64'),
+    };
+}
+/**
+ * Convert a 64-char raw hex string to base64.
+ * Convenience wrapper for assembling the x-amz-checksum-sha256 value from a
+ * hex content_hash that was returned by the API or read from a pointer file.
+ */
+export function hexToBase64(hex) {
+    return Buffer.from(hex, 'hex').toString('base64');
+}
+//# sourceMappingURL=assetHash.js.map

package/dist/lib/assetHash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetHash.js","sourceRoot":"","sources":["../../src/lib/assetHash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAWhD;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;IAE1C,OAAO,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAE1C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;YAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YACpB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7B,OAAO,CAAC;gBACN,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAC3B,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBACjC,SAAS;aACV,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;IACzD,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;KAClC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACpD,CAAC"}

package/dist/lib/assetUri.d.ts

@@ -0,0 +1,29 @@
+/**
+ * F54 — Asset URI parse / validate helpers.
+ *
+ * URI format: fazemos-asset://<org_slug>/<project_slug>/<sha256_hex>
+ *
+ * AC-F54-15: resolution walks the URI, not the pointer path — a pointer rename
+ * is benign because we always extract the URI and use it as the source of truth.
+ */
+export declare const ASSET_URI_PREFIX = "fazemos-asset://";
+/**
+ * Regex that matches a valid fazemos-asset URI.
+ * Slug segments: 1–63 chars, lowercase alphanum and hyphen, must start/end with
+ * alphanum. Hash segment: exactly 64 lowercase hex chars.
+ */
+export declare const ASSET_URI_RE: RegExp;
+export interface AssetUriParts {
+    orgSlug: string;
+    projectSlug: string;
+    /** 64-char lowercase hex, no sha256: prefix */
+    hash: string;
+}
+/**
+ * Parse a fazemos-asset URI string.
+ * Throws a descriptive Error on mismatch (used by CLI for pre-flight rejection
+ * per rul_asset_store_content_hash_addressed and ec_raw_uri_pattern_mismatch).
+ */
+export declare function parseAssetUri(uri: string): AssetUriParts;
+/** Returns true when the string matches the full fazemos-asset URI pattern. */
+export declare function isAssetUri(value: string): boolean;

package/dist/lib/assetUri.js

@@ -0,0 +1,34 @@
+/**
+ * F54 — Asset URI parse / validate helpers.
+ *
+ * URI format: fazemos-asset://<org_slug>/<project_slug>/<sha256_hex>
+ *
+ * AC-F54-15: resolution walks the URI, not the pointer path — a pointer rename
+ * is benign because we always extract the URI and use it as the source of truth.
+ */
+export const ASSET_URI_PREFIX = 'fazemos-asset://';
+/**
+ * Regex that matches a valid fazemos-asset URI.
+ * Slug segments: 1–63 chars, lowercase alphanum and hyphen, must start/end with
+ * alphanum. Hash segment: exactly 64 lowercase hex chars.
+ */
+export const ASSET_URI_RE = /^fazemos-asset:\/\/([a-z0-9][a-z0-9-]{0,61}[a-z0-9]?)\/([a-z0-9][a-z0-9-]{0,61}[a-z0-9]?)\/([a-f0-9]{64})$/;
+/**
+ * Parse a fazemos-asset URI string.
+ * Throws a descriptive Error on mismatch (used by CLI for pre-flight rejection
+ * per rul_asset_store_content_hash_addressed and ec_raw_uri_pattern_mismatch).
+ */
+export function parseAssetUri(uri) {
+    const m = ASSET_URI_RE.exec(uri);
+    if (!m) {
+        throw new Error(`Malformed fazemos-asset URI: "${uri}"\n` +
+            `Expected: fazemos-asset://<org>/<project>/<64-char-sha256-hex>\n` +
+            `Hint: org/project slugs are lowercase alphanum + hyphen; hash is 64 hex chars.`);
+    }
+    return { orgSlug: m[1], projectSlug: m[2], hash: m[3] };
+}
+/** Returns true when the string matches the full fazemos-asset URI pattern. */
+export function isAssetUri(value) {
+    return ASSET_URI_RE.test(value);
+}
+//# sourceMappingURL=assetUri.js.map

package/dist/lib/assetUri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetUri.js","sourceRoot":"","sources":["../../src/lib/assetUri.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,4GAA4G,CAAC;AAS/G;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,iCAAiC,GAAG,KAAK;YACvC,kEAAkE;YAClE,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC"}

package/dist/lib/contentTypeInfer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * F54 — Extension → MIME type inference.
+ *
+ * Used by `fazemos asset put` when --content-type is not supplied.
+ * Falls back to application/octet-stream for unrecognised extensions.
+ *
+ * Sage §7 handoff 5 — canonical extension table for agent asset outputs.
+ */
+/**
+ * Infer the MIME content-type from a filename (using its extension).
+ * Handles compound extensions like .tar.gz before falling through to last-dot.
+ * Returns 'application/octet-stream' for unknown extensions.
+ */
+export declare function inferContentType(filename: string): string;

package/dist/lib/contentTypeInfer.js

@@ -0,0 +1,87 @@
+/**
+ * F54 — Extension → MIME type inference.
+ *
+ * Used by `fazemos asset put` when --content-type is not supplied.
+ * Falls back to application/octet-stream for unrecognised extensions.
+ *
+ * Sage §7 handoff 5 — canonical extension table for agent asset outputs.
+ */
+const MIME_MAP = {
+    // Text / markup
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.csv': 'text/csv',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.xml': 'text/xml',
+    '.css': 'text/css',
+    '.js': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.ts': 'text/typescript',
+    '.sh': 'text/x-shellscript',
+    '.py': 'text/x-python',
+    '.ini': 'text/plain',
+    // Application / structured data
+    '.json': 'application/json',
+    '.jsonl': 'application/x-ndjson',
+    '.ndjson': 'application/x-ndjson',
+    '.yaml': 'application/yaml',
+    '.yml': 'application/yaml',
+    '.toml': 'application/toml',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+    '.gz': 'application/gzip',
+    '.tar': 'application/x-tar',
+    '.7z': 'application/x-7z-compressed',
+    '.rar': 'application/x-rar-compressed',
+    '.bz2': 'application/x-bzip2',
+    // Images
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.tiff': 'image/tiff',
+    '.tif': 'image/tiff',
+    '.avif': 'image/avif',
+    // Video
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    // Audio
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    // Data / analytics
+    '.parquet': 'application/vnd.apache.parquet',
+    '.avro': 'application/avro',
+    '.arrow': 'application/vnd.apache.arrow.file',
+    // Fonts
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+};
+/**
+ * Infer the MIME content-type from a filename (using its extension).
+ * Handles compound extensions like .tar.gz before falling through to last-dot.
+ * Returns 'application/octet-stream' for unknown extensions.
+ */
+export function inferContentType(filename) {
+    const lower = filename.toLowerCase();
+    // Compound extensions — check before last-dot fallback
+    if (lower.endsWith('.tar.gz'))
+        return 'application/gzip';
+    if (lower.endsWith('.tar.bz2'))
+        return 'application/x-bzip2';
+    if (lower.endsWith('.tar.xz'))
+        return 'application/x-xz';
+    const lastDot = lower.lastIndexOf('.');
+    if (lastDot < 0)
+        return 'application/octet-stream';
+    const ext = lower.slice(lastDot);
+    return MIME_MAP[ext] ?? 'application/octet-stream';
+}
+//# sourceMappingURL=contentTypeInfer.js.map

package/dist/lib/contentTypeInfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentTypeInfer.js","sourceRoot":"","sources":["../../src/lib/contentTypeInfer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,QAAQ,GAA2B;IACvC,gBAAgB;IAChB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,iBAAiB;IACxB,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,iBAAiB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,YAAY;IACpB,gCAAgC;IAChC,OAAO,EAAE,kBAAkB;IAC3B,QAAQ,EAAE,sBAAsB;IAChC,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,kBAAkB;IAC1B,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,6BAA6B;IACpC,MAAM,EAAE,8BAA8B;IACtC,MAAM,EAAE,qBAAqB;IAC7B,SAAS;IACT,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,eAAe;IACvB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,cAAc;IACtB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,QAAQ;IACR,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,iBAAiB;IACzB,QAAQ;IACR,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,mBAAmB;IACnB,UAAU,EAAE,gCAAgC;IAC5C,OAAO,EAAE,kBAAkB;IAC3B,QAAQ,EAAE,mCAAmC;IAC7C,QAAQ;IACR,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IAErC,uDAAuD;IACvD,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,kBAAkB,CAAC;IACzD,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,qBAAqB,CAAC;IAC7D,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,kBAAkB,CAAC;IAEzD,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,0BAA0B,CAAC;IAEnD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,0BAA0B,CAAC;AACrD,CAAC"}

package/dist/lib/pointerFile.d.ts

@@ -0,0 +1,62 @@
+/**
+ * F54 — .asset.yaml pointer file: parse / emit / normalize.
+ *
+ * BD-1 (ratified Stakeholder Review 2026-08-08): YAML ONLY.
+ * The .asset.json escape hatch is permanently removed.
+ * One canonical format; extension must be .asset.yaml.
+ *
+ * Canonical field order (BD-1 / pointer_file_format.schema_fields_ordered):
+ *   uri, content_hash, size_bytes, content_type, created_at,
+ *   produced_by.{agent, execution_id, step_id}, consumer_tag, original_filename
+ *
+ * AC-F54-8: readPointerFile() surfaces field-level errors — missing fields are
+ *   named explicitly so the operator knows exactly what to fix.
+ */
+export interface PointerFileProducedBy {
+    agent: string;
+    execution_id: string | null;
+    step_id: string | null;
+}
+export interface PointerFileData {
+    /** fazemos-asset://org/project/sha256 */
+    uri: string;
+    /** sha256:<64-char-hex> — WITH the sha256: prefix (pointer-file convention) */
+    content_hash: string;
+    size_bytes: number;
+    content_type: string;
+    /** ISO-8601 UTC with Z suffix */
+    created_at: string;
+    produced_by: PointerFileProducedBy;
+    consumer_tag: string;
+    original_filename: string | null;
+}
+/**
+ * Parse and validate a .asset.yaml pointer file.
+ *
+ * Throws with field-level error messages on validation failure (AC-F54-8).
+ * Enforces .asset.yaml extension (rul_asset_store_pointer_format).
+ */
+export declare function readPointerFile(filePath: string): PointerFileData;
+/**
+ * Return the canonical YAML string for a pointer, including the comment header.
+ * Fields are emitted in BD-1 canonical order.
+ */
+export declare function buildPointerContent(data: PointerFileData): string;
+/**
+ * Write a .asset.yaml pointer file in canonical field order.
+ * Creates parent directories as needed.
+ * Enforces .asset.yaml extension (rul_asset_store_pointer_format).
+ */
+export declare function writePointerFile(filePath: string, data: PointerFileData): void;
+/**
+ * Normalize a `pointer` object from the put-url API response into PointerFileData.
+ *
+ * API's pointer.content_hash is already in `sha256:<hex>` format (per handoff notes).
+ * API's pointer.produced_by matches the pointer-file shape.
+ */
+export declare function pointerFromApiResponse(pointer: Record<string, unknown>): PointerFileData;
+/**
+ * Strip the `sha256:` prefix from a content_hash field (pointer-file convention)
+ * to get the raw 64-char hex required by the API.
+ */
+export declare function stripHashPrefix(contentHash: string): string;

package/dist/lib/pointerFile.js

@@ -0,0 +1,171 @@
+/**
+ * F54 — .asset.yaml pointer file: parse / emit / normalize.
+ *
+ * BD-1 (ratified Stakeholder Review 2026-08-08): YAML ONLY.
+ * The .asset.json escape hatch is permanently removed.
+ * One canonical format; extension must be .asset.yaml.
+ *
+ * Canonical field order (BD-1 / pointer_file_format.schema_fields_ordered):
+ *   uri, content_hash, size_bytes, content_type, created_at,
+ *   produced_by.{agent, execution_id, step_id}, consumer_tag, original_filename
+ *
+ * AC-F54-8: readPointerFile() surfaces field-level errors — missing fields are
+ *   named explicitly so the operator knows exactly what to fix.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import yaml from 'js-yaml';
+// ── Constants ─────────────────────────────────────────────────────────────────
+const COMMENT_HEADER = '# fazemos-asset pointer — this file replaces a large binary in the repo.\n' +
+    '# The underlying bytes live in the Fazemos asset store; resolve with\n' +
+    '# `fazemos asset get <this-file>` or `fazemos asset show <this-file>`.';
+const REQUIRED_FIELDS = [
+    'uri',
+    'content_hash',
+    'size_bytes',
+    'content_type',
+    'created_at',
+    'produced_by',
+    'consumer_tag',
+];
+const REQUIRED_PRODUCED_BY_FIELDS = [
+    'agent',
+    'execution_id',
+    'step_id',
+];
+// ── Read ──────────────────────────────────────────────────────────────────────
+/**
+ * Parse and validate a .asset.yaml pointer file.
+ *
+ * Throws with field-level error messages on validation failure (AC-F54-8).
+ * Enforces .asset.yaml extension (rul_asset_store_pointer_format).
+ */
+export function readPointerFile(filePath) {
+    if (!filePath.endsWith('.asset.yaml')) {
+        throw new Error(`Pointer files must use the .asset.yaml extension (got: ${filePath})\n` +
+            `Hint: pass the raw fazemos-asset:// URI directly, or rename the file.`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Cannot read pointer file '${filePath}': ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (err) {
+        throw new Error(`Pointer file '${filePath}' is not valid YAML: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Pointer file '${filePath}' is empty or not a YAML object.`);
+    }
+    const data = parsed;
+    // Field-level validation (AC-F54-8)
+    const missing = [];
+    for (const field of REQUIRED_FIELDS) {
+        if (data[field] === undefined) {
+            missing.push(field);
+        }
+    }
+    // Validate produced_by sub-fields
+    if (data['produced_by'] !== undefined && data['produced_by'] !== null) {
+        if (typeof data['produced_by'] === 'object' && !Array.isArray(data['produced_by'])) {
+            const pb = data['produced_by'];
+            for (const field of REQUIRED_PRODUCED_BY_FIELDS) {
+                if (!(field in pb)) {
+                    missing.push(`produced_by.${field}`);
+                }
+            }
+        }
+        else {
+            missing.push('produced_by.agent', 'produced_by.execution_id', 'produced_by.step_id');
+        }
+    }
+    else if (!missing.includes('produced_by')) {
+        missing.push('produced_by.agent', 'produced_by.execution_id', 'produced_by.step_id');
+    }
+    if (missing.length > 0) {
+        throw new Error(`Pointer file '${filePath}' is missing required fields: ${missing.join(', ')}\n` +
+            `The file may be truncated, hand-edited incorrectly, or from an older format version.`);
+    }
+    return data;
+}
+// ── Write ─────────────────────────────────────────────────────────────────────
+/**
+ * Return the canonical YAML string for a pointer, including the comment header.
+ * Fields are emitted in BD-1 canonical order.
+ */
+export function buildPointerContent(data) {
+    // Construct in canonical field order (BD-1)
+    const ordered = {
+        uri: data.uri,
+        content_hash: data.content_hash,
+        size_bytes: data.size_bytes,
+        content_type: data.content_type,
+        created_at: data.created_at,
+        produced_by: {
+            agent: data.produced_by.agent,
+            execution_id: data.produced_by.execution_id,
+            step_id: data.produced_by.step_id,
+        },
+        consumer_tag: data.consumer_tag,
+        original_filename: data.original_filename ?? null,
+    };
+    const yamlBody = yaml.dump(ordered, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+        indent: 2,
+    });
+    return `${COMMENT_HEADER}\n${yamlBody}`;
+}
+/**
+ * Write a .asset.yaml pointer file in canonical field order.
+ * Creates parent directories as needed.
+ * Enforces .asset.yaml extension (rul_asset_store_pointer_format).
+ */
+export function writePointerFile(filePath, data) {
+    if (!filePath.endsWith('.asset.yaml')) {
+        throw new Error(`Pointer file path must end in .asset.yaml (got: ${filePath})`);
+    }
+    const dir = dirname(filePath);
+    if (dir && dir !== '.') {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, buildPointerContent(data), 'utf-8');
+}
+// ── API response normalization ────────────────────────────────────────────────
+/**
+ * Normalize a `pointer` object from the put-url API response into PointerFileData.
+ *
+ * API's pointer.content_hash is already in `sha256:<hex>` format (per handoff notes).
+ * API's pointer.produced_by matches the pointer-file shape.
+ */
+export function pointerFromApiResponse(pointer) {
+    const pb = pointer['produced_by'] ?? {};
+    return {
+        uri: String(pointer['uri'] ?? ''),
+        content_hash: String(pointer['content_hash'] ?? ''),
+        size_bytes: Number(pointer['size_bytes'] ?? 0),
+        content_type: String(pointer['content_type'] ?? ''),
+        created_at: String(pointer['created_at'] ?? ''),
+        produced_by: {
+            agent: String(pb['agent'] ?? 'fazemos-cli'),
+            execution_id: pb['execution_id'] != null ? String(pb['execution_id']) : null,
+            step_id: pb['step_id'] != null ? String(pb['step_id']) : null,
+        },
+        consumer_tag: String(pointer['consumer_tag'] ?? ''),
+        original_filename: pointer['original_filename'] != null ? String(pointer['original_filename']) : null,
+    };
+}
+/**
+ * Strip the `sha256:` prefix from a content_hash field (pointer-file convention)
+ * to get the raw 64-char hex required by the API.
+ */
+export function stripHashPrefix(contentHash) {
+    return contentHash.startsWith('sha256:') ? contentHash.slice(7) : contentHash;
+}
+//# sourceMappingURL=pointerFile.js.map

package/dist/lib/pointerFile.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formigio/fazemos-cli",
-  "version": "0.10.64",
+  "version": "0.10.67",
   "description": "CLI for the Fazemos Team Accomplishment Platform",
   "type": "module",
   "license": "MIT",