my-frontend-observer 0.5.0 → 0.7.0

package/dist/artifacts/externalReferenceArtifactWriter.d.ts

@@ -0,0 +1,44 @@
+import type { ExternalReferenceArtifact } from '../domain/externalReference.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const EXTERNAL_REFERENCE_MANIFEST_FILENAME = "manifest.json";
+/**
+ * Observer-owned result of persisting one ExternalReferenceArtifact. Mirrors
+ * PersistedObservationResult/PersistedComparisonResult's shape but is its own
+ * type: an 'imported' artifact's directory has one owned image file; an
+ * 'approved' artifact's directory has only manifest.json.
+ */
+export type PersistedExternalReferenceResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+    imagePath?: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteExternalReferenceArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Persists one already-assembled, already-validated ExternalReferenceArtifact
+ * as one portable artifact directory: `<outputLocation>/<referenceId>/`.
+ * For an 'imported' artifact (which owns its reference image), `imageBytes`
+ * is required and is written before manifest.json, mirroring
+ * `artifacts/artifactWriter.ts#writeObservationArtifact`'s media-before-manifest
+ * discipline. For an 'approved' artifact (which only ever carries a
+ * `sourceReference` back to the imported artifact that owns the image - see
+ * `domain/externalReference.ts`), no image bytes are written at all, mirroring
+ * `artifacts/comparisonArtifactWriter.ts#writeComparisonArtifact`'s
+ * manifest-only, no-media-copy persistence.
+ *
+ * `referenceId` is guaranteed fresh per persisted instance (see
+ * `domain/externalReferenceIdentity.ts#buildExternalReferenceInstanceIdentity`'s
+ * "never collides" contract), so each write targets its own unique
+ * subdirectory; an existing directory at that path is treated as a genuine
+ * collision and rejected rather than overwritten - no persisted evidence,
+ * imported or approved, is ever destructively replaced. Writing happens in a
+ * sibling temporary directory first, and the whole temporary directory is
+ * only exposed under its real name via one atomic rename.
+ */
+export declare function writeExternalReferenceArtifact(artifact: ExternalReferenceArtifact, imageBytes: Uint8Array | undefined, outputLocation: string, options?: WriteExternalReferenceArtifactOptions): Promise<PersistedExternalReferenceResult>;

package/dist/artifacts/externalReferenceArtifactWriter.js

@@ -0,0 +1,77 @@
+import { mkdir, writeFile, rename, rm, access } from 'node:fs/promises';
+import path from 'node:path';
+import { isValidExternalReferenceArtifact, isImportedExternalReferenceArtifact } from '../domain/externalReference.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+export const EXTERNAL_REFERENCE_MANIFEST_FILENAME = 'manifest.json';
+function writeFailure(message, details) {
+    const diagnostic = {
+        code: 'artifact-write-failure',
+        severity: DIAGNOSTIC_SEVERITY['artifact-write-failure'],
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+    return { ok: false, diagnostics: [diagnostic] };
+}
+async function pathExists(candidate) {
+    return access(candidate).then(() => true, () => false);
+}
+/**
+ * Persists one already-assembled, already-validated ExternalReferenceArtifact
+ * as one portable artifact directory: `<outputLocation>/<referenceId>/`.
+ * For an 'imported' artifact (which owns its reference image), `imageBytes`
+ * is required and is written before manifest.json, mirroring
+ * `artifacts/artifactWriter.ts#writeObservationArtifact`'s media-before-manifest
+ * discipline. For an 'approved' artifact (which only ever carries a
+ * `sourceReference` back to the imported artifact that owns the image - see
+ * `domain/externalReference.ts`), no image bytes are written at all, mirroring
+ * `artifacts/comparisonArtifactWriter.ts#writeComparisonArtifact`'s
+ * manifest-only, no-media-copy persistence.
+ *
+ * `referenceId` is guaranteed fresh per persisted instance (see
+ * `domain/externalReferenceIdentity.ts#buildExternalReferenceInstanceIdentity`'s
+ * "never collides" contract), so each write targets its own unique
+ * subdirectory; an existing directory at that path is treated as a genuine
+ * collision and rejected rather than overwritten - no persisted evidence,
+ * imported or approved, is ever destructively replaced. Writing happens in a
+ * sibling temporary directory first, and the whole temporary directory is
+ * only exposed under its real name via one atomic rename.
+ */
+export async function writeExternalReferenceArtifact(artifact, imageBytes, outputLocation, options = {}) {
+    const validation = isValidExternalReferenceArtifact(artifact);
+    if (!validation.valid) {
+        return writeFailure(`refusing to persist an invalid ExternalReferenceArtifact: ${validation.reason}`);
+    }
+    if (artifact.lifecycle.state === 'imported' && imageBytes === undefined) {
+        return writeFailure('refusing to persist an "imported" ExternalReferenceArtifact without its image bytes');
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const outputRoot = path.resolve(cwd, outputLocation);
+    const finalRoot = path.join(outputRoot, artifact.referenceId);
+    const tempRoot = path.join(outputRoot, `.tmp-${artifact.referenceId}`);
+    if (await pathExists(finalRoot)) {
+        return writeFailure(`an external-reference artifact already exists at "${artifact.referenceId}"; refusing to overwrite it`, {
+            artifactRoot: finalRoot,
+        });
+    }
+    try {
+        await rm(tempRoot, { recursive: true, force: true });
+        await mkdir(tempRoot, { recursive: true });
+        if (isImportedExternalReferenceArtifact(artifact)) {
+            await writeFile(path.join(tempRoot, artifact.image.path), imageBytes);
+        }
+        await writeFile(path.join(tempRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME), JSON.stringify(artifact, null, 2), 'utf8');
+        await rename(tempRoot, finalRoot);
+        return {
+            ok: true,
+            artifactRoot: finalRoot,
+            manifestPath: path.join(finalRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME),
+            ...(isImportedExternalReferenceArtifact(artifact) ? { imagePath: path.join(finalRoot, artifact.image.path) } : {}),
+        };
+    }
+    catch (err) {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        return writeFailure(`failed to persist external-reference artifact: ${message}`);
+    }
+}
+//# sourceMappingURL=externalReferenceArtifactWriter.js.map

package/dist/artifacts/externalReferenceArtifactWriter.js.map

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