@ectplsm/relic 0.5.0 → 0.5.1

package/README.md

@@ -188,6 +188,8 @@ For LLM-assisted creation, persona authoring, template examples, and deletion ru
 
 Relic can push plaintext persona files and (end-to-end) encrypted memory files to [Mikoshi](https://mikoshi.ectplsm.com), so you can keep Engrams in the cloud and move them across machines without turning Mikoshi into your authoring source of truth.
 
+This includes avatar-aware persona push/pull: local image paths and external `https://` avatar URLs can be snapshotted into Mikoshi-managed storage during `relic mikoshi push`.
+
 For setup, API key configuration, persona push/pull, encrypted memory sync, and the recommended command flow, see [docs/mikoshi.md](docs/mikoshi.md).
 
 ## Configuration

package/dist/adapters/local/local-engram-repository.d.ts

@@ -1,4 +1,4 @@
-import type { Engram, EngramMeta } from "../../core/entities/engram.js";
+import type { Engram, EngramManifest, EngramMeta } from "../../core/entities/engram.js";
 import type { EngramRepository } from "../../core/ports/engram-repository.js";
 /**
  * LocalEngramRepository — ローカルファイルシステム上の
@@ -24,6 +24,8 @@ export declare class LocalEngramRepository implements EngramRepository {
     get(id: string): Promise<Engram | null>;
     save(engram: Engram): Promise<void>;
     delete(id: string): Promise<void>;
+    getEngramPath(id: string): string;
+    updateManifest(id: string, manifest: EngramManifest): Promise<void>;
     copyArchiveFiles(fromId: string, toId: string): Promise<boolean>;
     private readMeta;
     private toProfile;

package/dist/adapters/local/local-engram-repository.js

@@ -91,6 +91,27 @@ export class LocalEngramRepository {
             await rm(engramDir, { recursive: true });
         }
     }
+    getEngramPath(id) {
+        return join(this.basePath, id);
+    }
+    async updateManifest(id, manifest) {
+        const engramDir = join(this.basePath, id);
+        if (!existsSync(engramDir))
+            return;
+        const manifestPath = join(engramDir, MANIFEST_FILE);
+        const payload = {
+            id: manifest.id,
+            createdAt: manifest.createdAt,
+            updatedAt: manifest.updatedAt,
+            ...(manifest.avatarHash !== undefined
+                ? { avatarHash: manifest.avatarHash }
+                : {}),
+            ...(manifest.avatarSourceUrl !== undefined
+                ? { avatarSourceUrl: manifest.avatarSourceUrl }
+                : {}),
+        };
+        await writeFile(manifestPath, JSON.stringify(payload, null, 2), "utf-8");
+    }
     async copyArchiveFiles(fromId, toId) {
         const ARCHIVE_FILES = ["archive.md", "archive.cursor"];
         const fromDir = join(this.basePath, fromId);
@@ -148,6 +169,10 @@ export class LocalEngramRepository {
             id: meta.id,
             createdAt: meta.createdAt,
             updatedAt: meta.updatedAt,
+            ...(meta.avatarHash !== undefined ? { avatarHash: meta.avatarHash } : {}),
+            ...(meta.avatarSourceUrl !== undefined
+                ? { avatarSourceUrl: meta.avatarSourceUrl }
+                : {}),
         };
     }
     async writeMetaFiles(engramDir, meta) {

package/dist/adapters/mikoshi/client.d.ts

@@ -1,4 +1,4 @@
-import { type MikoshiClient, type MikoshiEngram, type MikoshiEngramDetail, type CreateEngramInput, type CreateEngramResponse, type SyncStatusResponse, type UpdatePersonaInput, type UpdatePersonaResponse, type UploadMemoryInput, type UploadMemoryResponse, type DownloadMemoryResponse } from "../../core/ports/mikoshi.js";
+import { type MikoshiClient, type MikoshiEngram, type MikoshiEngramDetail, type CreateEngramInput, type CreateEngramResponse, type SyncStatusResponse, type UpdatePersonaInput, type UpdatePersonaResponse, type UploadMemoryInput, type UploadMemoryResponse, type DownloadMemoryResponse, type UploadEngramAvatarResponse, type DeleteEngramAvatarResponse } from "../../core/ports/mikoshi.js";
 /**
  * MikoshiApiClient — Mikoshi REST API v1 の adapter 実装
  *
@@ -17,5 +17,7 @@ export declare class MikoshiApiClient implements MikoshiClient {
     updatePersona(engramId: string, input: UpdatePersonaInput): Promise<UpdatePersonaResponse>;
     uploadMemory(engramId: string, input: UploadMemoryInput): Promise<UploadMemoryResponse>;
     downloadMemory(engramId: string): Promise<DownloadMemoryResponse>;
+    uploadEngramAvatar(engramId: string, data: Buffer, mimeType: string): Promise<UploadEngramAvatarResponse>;
+    deleteEngramAvatar(engramId: string): Promise<DeleteEngramAvatarResponse>;
     private request;
 }

package/dist/adapters/mikoshi/client.js

@@ -1,4 +1,4 @@
-import { MikoshiApiError, MikoshiEngramSchema, MikoshiEngramDetailSchema, CreateEngramResponseSchema, SyncStatusResponseSchema, UpdatePersonaResponseSchema, UploadMemoryResponseSchema, DownloadMemoryResponseSchema, } from "../../core/ports/mikoshi.js";
+import { MikoshiApiError, MikoshiEngramSchema, MikoshiEngramDetailSchema, CreateEngramResponseSchema, SyncStatusResponseSchema, UpdatePersonaResponseSchema, UploadMemoryResponseSchema, DownloadMemoryResponseSchema, UploadEngramAvatarResponseSchema, DeleteEngramAvatarResponseSchema, } from "../../core/ports/mikoshi.js";
 import { z } from "zod";
 /**
  * MikoshiApiClient — Mikoshi REST API v1 の adapter 実装
@@ -49,6 +49,18 @@ export class MikoshiApiClient {
         const data = await this.request("GET", `/api/v1/engrams/${enc(engramId)}/memory`);
         return DownloadMemoryResponseSchema.parse(data);
     }
+    async uploadEngramAvatar(engramId, data, mimeType) {
+        const form = new FormData();
+        // Blob は Uint8Array を受け付ける (Node 18+ 標準)
+        const blob = new Blob([new Uint8Array(data)], { type: mimeType });
+        form.append("file", blob, filenameForMimeType(mimeType));
+        const raw = await this.request("PUT", `/api/v1/engrams/${enc(engramId)}/avatar`, form);
+        return UploadEngramAvatarResponseSchema.parse(raw);
+    }
+    async deleteEngramAvatar(engramId) {
+        const raw = await this.request("DELETE", `/api/v1/engrams/${enc(engramId)}/avatar`);
+        return DeleteEngramAvatarResponseSchema.parse(raw);
+    }
     // -----------------------------------------------------------------------
     // Internal
     // -----------------------------------------------------------------------
@@ -60,8 +72,14 @@ export class MikoshiApiClient {
         };
         const init = { method, headers };
         if (body !== undefined) {
-            headers["Content-Type"] = "application/json";
-            init.body = JSON.stringify(body);
+            if (body instanceof FormData) {
+                // multipart boundary は fetch に自動で決めさせる
+                init.body = body;
+            }
+            else {
+                headers["Content-Type"] = "application/json";
+                init.body = JSON.stringify(body);
+            }
         }
         const res = await fetch(url, init);
         if (!res.ok) {
@@ -82,3 +100,15 @@ export class MikoshiApiClient {
 function enc(segment) {
     return encodeURIComponent(segment);
 }
+/**
+ * multipart/form-data 送信時のダミーファイル名。
+ * Mikoshi 側は MIME と内容で判定するので拡張子さえ合っていればよい。
+ */
+function filenameForMimeType(mimeType) {
+    switch (mimeType) {
+        case "image/jpeg": return "avatar.jpg";
+        case "image/png": return "avatar.png";
+        case "image/webp": return "avatar.webp";
+        default: return "avatar";
+    }
+}

package/dist/core/entities/engram.d.ts

@@ -66,14 +66,22 @@ export declare const EngramManifestSchema: z.ZodObject<{
     createdAt: z.ZodString;
     /** 最終更新日時 */
     updatedAt: z.ZodString;
+    /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+    avatarHash: z.ZodOptional<z.ZodString>;
+    /** 前回 push 時に使った外部 avatar URL */
+    avatarSourceUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     createdAt: string;
     updatedAt: string;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }, {
     id: string;
     createdAt: string;
     updatedAt: string;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }>;
 export type EngramManifest = z.infer<typeof EngramManifestSchema>;
 /**
@@ -93,6 +101,10 @@ export declare const EngramMetaSchema: z.ZodObject<{
     createdAt: z.ZodString;
     /** 最終更新日時 */
     updatedAt: z.ZodString;
+    /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+    avatarHash: z.ZodOptional<z.ZodString>;
+    /** 前回 push 時に使った外部 avatar URL */
+    avatarSourceUrl: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     id: string;
@@ -100,6 +112,8 @@ export declare const EngramMetaSchema: z.ZodObject<{
     updatedAt: string;
     description?: string | undefined;
     tags?: string[] | undefined;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }, {
     name: string;
     id: string;
@@ -107,6 +121,8 @@ export declare const EngramMetaSchema: z.ZodObject<{
     updatedAt: string;
     description?: string | undefined;
     tags?: string[] | undefined;
+    avatarHash?: string | undefined;
+    avatarSourceUrl?: string | undefined;
 }>;
 export type EngramMeta = z.infer<typeof EngramMetaSchema>;
 /**
@@ -128,6 +144,10 @@ export declare const EngramSchema: z.ZodObject<{
         createdAt: z.ZodString;
         /** 最終更新日時 */
         updatedAt: z.ZodString;
+        /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+        avatarHash: z.ZodOptional<z.ZodString>;
+        /** 前回 push 時に使った外部 avatar URL */
+        avatarSourceUrl: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         id: string;
@@ -135,6 +155,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     }, {
         name: string;
         id: string;
@@ -142,6 +164,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     }>;
     files: z.ZodObject<{
         /** 人格の核となる指示・行動原理 */
@@ -183,6 +207,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     };
     files: {
         soul: string;
@@ -201,6 +227,8 @@ export declare const EngramSchema: z.ZodObject<{
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
+        avatarHash?: string | undefined;
+        avatarSourceUrl?: string | undefined;
     };
     files: {
         soul: string;

package/dist/core/entities/engram.js

@@ -43,6 +43,10 @@ export const EngramManifestSchema = z.object({
     createdAt: z.string().datetime(),
     /** 最終更新日時 */
     updatedAt: z.string().datetime(),
+    /** 前回 push 時の avatar 画像ファイルの SHA-256 ハッシュ */
+    avatarHash: z.string().optional(),
+    /** 前回 push 時に使った外部 avatar URL */
+    avatarSourceUrl: z.string().url().optional(),
 });
 /**
  * Engramメタデータ — プロフィールとマニフェストを結合した利用時ビュー

package/dist/core/ports/engram-repository.d.ts

@@ -1,4 +1,4 @@
-import type { Engram, EngramMeta } from "../entities/engram.js";
+import type { Engram, EngramManifest, EngramMeta } from "../entities/engram.js";
 /**
  * EngramRepository — Engram永続化層の抽象ポート
  *
@@ -12,8 +12,24 @@ export interface EngramRepository {
     get(id: string): Promise<Engram | null>;
     /** Engramを保存（作成 or 更新） */
     save(engram: Engram): Promise<void>;
+    /**
+     * マニフェストだけを差分書き換えする軽量更新。
+     *
+     * `save()` は全ファイルを書き戻してしまうので、avatarHash のような
+     * マニフェスト内のフィールドだけを安全に更新したい時に使う。
+     * 対象 Engram が存在しない場合の挙動は実装に委ねる（例外または no-op）。
+     */
+    updateManifest(id: string, manifest: EngramManifest): Promise<void>;
     /** Engramを削除 */
     delete(id: string): Promise<void>;
     /** アーカイブファイル (archive.md, archive.cursor) を別Engramへコピー */
     copyArchiveFiles(fromId: string, toId: string): Promise<boolean>;
+    /**
+     * Engramのディレクトリ絶対パスを返す。
+     *
+     * 存在判定は行わず、リポジトリが想定するパスを返すだけ。
+     * avatar 画像の読み書きなどファイルシステム直接アクセスが必要な
+     * usecase から使う。リモート専用リポジトリでは null を返してよい。
+     */
+    getEngramPath(id: string): string | null;
 }

package/dist/core/ports/mikoshi.d.ts

@@ -906,6 +906,26 @@ export declare const DownloadMemoryResponseSchema: z.ZodDiscriminatedUnion<"hasM
     engramId: string;
 }>]>;
 export type DownloadMemoryResponse = z.infer<typeof DownloadMemoryResponseSchema>;
+/** クライアントが許可する avatar MIME タイプ */
+export declare const AVATAR_SUPPORTED_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/webp"];
+/** クライアント側事前バリデーションの最大バイト数 (Mikoshi 側と一致) */
+export declare const AVATAR_MAX_BYTES: number;
+export declare const UploadEngramAvatarResponseSchema: z.ZodObject<{
+    avatarUrl: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    avatarUrl: string;
+}, {
+    avatarUrl: string;
+}>;
+export type UploadEngramAvatarResponse = z.infer<typeof UploadEngramAvatarResponseSchema>;
+export declare const DeleteEngramAvatarResponseSchema: z.ZodObject<{
+    avatarUrl: z.ZodNull;
+}, "strip", z.ZodTypeAny, {
+    avatarUrl: null;
+}, {
+    avatarUrl: null;
+}>;
+export type DeleteEngramAvatarResponse = z.infer<typeof DeleteEngramAvatarResponseSchema>;
 export declare class MikoshiApiError extends Error {
     readonly status: number;
     readonly code: string | undefined;
@@ -934,4 +954,8 @@ export interface MikoshiClient {
     uploadMemory(engramId: string, input: UploadMemoryInput): Promise<UploadMemoryResponse>;
     /** 暗号化メモリバンドルをダウンロード */
     downloadMemory(engramId: string): Promise<DownloadMemoryResponse>;
+    /** Avatar 画像をアップロード (multipart/form-data) */
+    uploadEngramAvatar(engramId: string, data: Buffer, mimeType: string): Promise<UploadEngramAvatarResponse>;
+    /** Avatar 画像を削除 */
+    deleteEngramAvatar(engramId: string): Promise<DeleteEngramAvatarResponse>;
 }

package/dist/core/ports/mikoshi.js

@@ -188,6 +188,23 @@ export const DownloadMemoryResponseSchema = z.discriminatedUnion("hasMemory", [
     }),
 ]);
 // ---------------------------------------------------------------------------
+// Avatar upload / delete
+// ---------------------------------------------------------------------------
+/** クライアントが許可する avatar MIME タイプ */
+export const AVATAR_SUPPORTED_MIME_TYPES = [
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+];
+/** クライアント側事前バリデーションの最大バイト数 (Mikoshi 側と一致) */
+export const AVATAR_MAX_BYTES = 2 * 1024 * 1024;
+export const UploadEngramAvatarResponseSchema = z.object({
+    avatarUrl: z.string(),
+});
+export const DeleteEngramAvatarResponseSchema = z.object({
+    avatarUrl: z.null(),
+});
+// ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
 export class MikoshiApiError extends Error {

package/dist/core/sync/avatar.d.ts

@@ -0,0 +1,121 @@
+export type AvatarRef = {
+    kind: "path";
+    value: string;
+} | {
+    kind: "url";
+    value: string;
+};
+export interface FetchedAvatar {
+    bytes: Buffer;
+    mimeType: string;
+    finalUrl: string;
+}
+/**
+ * IDENTITY.md から Avatar フィールドの生の値を抽出する。
+ *
+ * - マッチしなければ null
+ * - 値が URL（http://, https://）の場合は Mikoshi 管理外として null
+ * - 空白のみの値も null として扱う
+ */
+export declare function parseAvatarPath(identity: string): string | null;
+/**
+ * IDENTITY.md から Avatar フィールドの参照先を抽出する。
+ *
+ * - マッチしなければ null
+ * - 空白のみの値も null
+ * - `http(s)://` は URL として返す
+ * - それ以外は path として返す
+ */
+export declare function parseAvatarRef(identity: string): AvatarRef | null;
+/**
+ * Avatar パスを絶対パスに解決する。
+ *
+ * - 絶対パス → そのまま
+ * - 相対パス → Engram ディレクトリ基準で resolve
+ */
+export declare function resolveAvatarPath(rawPath: string, engramDir: string): string;
+/**
+ * ファイル内容の SHA-256 ハッシュを計算する。
+ *
+ * 出力形式: "sha256:<64 lowercase hex>"
+ *
+ * ストリーム処理なので 2MB 制限を超える巨大ファイルでも OOM しない。
+ */
+export declare function computeAvatarHash(filePath: string): Promise<string>;
+export declare function computeAvatarHashFromBytes(bytes: Uint8Array): string;
+/**
+ * 拡張子から MIME タイプを判定する。
+ *
+ * 許可フォーマット: JPEG, PNG, WebP
+ * 対応外なら null（呼び出し側でエラーにする）
+ *
+ * バイナリ判定は Mikoshi 側の sharp に任せる方針。
+ * クライアントは軽量な事前バリデーションのみ。
+ */
+export declare function detectAvatarMimeType(filePath: string): string | null;
+/**
+ * レスポンス header / magic number の両方から MIME を判定する。
+ *
+ * 両方あって不一致なら null を返す。
+ */
+export declare function detectAvatarMimeTypeFromBytes(bytes: Uint8Array, headerMimeType?: string | null): string | null;
+export declare function isHttpsUrl(raw: string): boolean;
+/**
+ * ホストが private / loopback / link-local なら true。
+ *
+ * hostname の場合は DNS lookup して、返ってきた全アドレスを検査する。
+ * DNS rebinding の完全対策ではない。事故防止用。
+ */
+export declare function isPrivateHost(url: URL): Promise<boolean>;
+export declare function fetchAvatarFromUrl(url: string, maxBytes: number, timeoutMs: number): Promise<FetchedAvatar>;
+/**
+ * IDENTITY.md を Avatar 行の前後で分離した結果。
+ *
+ * Avatar 行が存在しない場合は `rawValue === null`、`before` に全内容、
+ * `after` に空文字が入る（呼び出し側が「Avatar 行無し」として判定できる）。
+ */
+export interface AvatarSplit {
+    /** Avatar 行の値の直前までの文字列（`- **Avatar:** ` prefix を含む） */
+    before: string;
+    /** Avatar 行の値（行末改行含まず）。Avatar 行が無ければ null */
+    rawValue: string | null;
+    /** Avatar 行の値の直後以降の文字列（行末改行とその後の内容） */
+    after: string;
+}
+/**
+ * IDENTITY.md を Avatar 行の値を境に前後分離する。
+ *
+ * 書き換えと drift 検出の両方で使う基本操作。
+ */
+export declare function splitAroundAvatar(identity: string): AvatarSplit;
+/**
+ * IDENTITY.md の Avatar 行の値だけを差し替えて新しい文字列を返す。
+ *
+ * Avatar 行が存在しない場合は元の identity をそのまま返す
+ * （新しい Avatar 行は挿入しない — 保守的な挙動）。
+ */
+export declare function rewriteAvatarValue(identity: string, newValue: string): string;
+/**
+ * avatar-only drift の検出結果。
+ *
+ * drift === true の場合のみ `localValue` / `remoteValue` が
+ * 非 null（両方に Avatar 行が存在し、値だけが違う）。
+ */
+export interface AvatarOnlyDrift {
+    drift: boolean;
+    localValue: string | null;
+    remoteValue: string | null;
+}
+/**
+ * 2つの IDENTITY.md の差分が Avatar 行の値だけかどうかを判定する。
+ *
+ * 判定条件:
+ * - 両方に Avatar 行が存在する
+ * - Avatar 行の前後 (`before` / `after`) が完全一致
+ * - Avatar 行の値だけ異なる
+ *
+ * PATH 前後の format 揺れ（改行数・空白数など）は
+ * `before` / `after` の文字列一致にそのまま反映されるため、
+ * 揺れがあれば avatar-only drift とは判定されない（false positive を避ける）。
+ */
+export declare function isAvatarOnlyDrift(local: string, remote: string): AvatarOnlyDrift;