@semiont/content 0.3.7 → 0.4.0

package/dist/index.d.ts

@@ -2,96 +2,130 @@ import { SemiontProject } from '@semiont/core/node';
 import { Logger } from '@semiont/core';
 
 /**
- * RepresentationStore - Content-addressed storage for byte-level resource representations
+ * WorkingTreeStore - Manages files in the project working tree
  *
- * Handles storage and retrieval of concrete byte-level renditions of resources.
- * Uses content-addressed storage where the checksum IS the filename.
- * Supports multiple storage backends (filesystem, S3, IPFS, etc.)
+ * Unlike the old content-addressed RepresentationStore, this store treats
+ * the working tree (project root) as the source of truth for file content.
+ * Resources are identified by their file:// URI, which is stable across
+ * content changes and moves (tracked by events).
  *
- * Storage structure (filesystem):
- * basePath/representations/{mediaType}/{ab}/{cd}/rep-{checksum}{extension}
+ * Two write paths:
+ * - store(content, storageUri): Write bytes to disk (API/GUI/AI path).
+ *   Used when the file does not yet exist and the caller provides content.
+ * - register(storageUri, expectedChecksum?): Read an existing file and
+ *   return its metadata (CLI path). The file is already on disk; we just
+ *   verify and record it. If expectedChecksum is provided, throws on mismatch.
  *
- * Where:
- * - {mediaType} is base MIME type with "/" encoded as "~1" (e.g., "text~1markdown")
- * - {ab}/{cd} are first 4 hex digits of checksum for sharding
- * - {checksum} is the raw SHA-256 hex hash (e.g., "5aaa0b72abc123...")
- * - {extension} is derived from base MIME type (.md, .txt, .png, etc.)
+ * Storage layout:
+ *   {projectRoot}/{path-from-uri}
  *
- * Example:
- * For content with checksum "5aaa0b72abc123..." and mediaType "text/markdown; charset=iso-8859-1":
- * - Storage path: basePath/representations/text~1markdown/5a/aa/rep-5aaa0b72abc123....md
- * - Stored mediaType: "text/markdown; charset=iso-8859-1" (full type with charset preserved)
- *
- * Character Encoding:
- * - Charset parameters in mediaType are preserved in metadata (e.g., "text/plain; charset=iso-8859-1")
- * - Storage path uses only base MIME type (strips charset for directory structure)
- * - Content stored as raw bytes - charset only affects decoding on retrieval
- *
- * This design provides:
- * - O(1) content retrieval by checksum + mediaType
- * - Automatic deduplication (identical content = same file)
- * - Idempotent storage operations
- * - Proper file extensions for filesystem browsing
- * - Faithful preservation of character encoding metadata
+ * For example, storageUri "file://docs/overview.md" resolves to
+ *   {projectRoot}/docs/overview.md
  */
 
 /**
- * Metadata for a representation being stored
- */
-interface RepresentationMetadata {
-    mediaType: string;
-    filename?: string;
-    encoding?: string;
-    language?: string;
-    rel?: 'original' | 'thumbnail' | 'preview' | 'optimized' | 'derived' | 'other';
-}
-/**
- * Complete representation information
+ * Result of store() or register()
  */
-interface StoredRepresentation extends RepresentationMetadata {
-    '@id': string;
-    byteSize: number;
+interface StoredResource {
+    storageUri: string;
     checksum: string;
+    byteSize: number;
     created: string;
 }
 /**
- * Interface for representation storage backends
+ * Manages files in the project working tree
  */
-interface RepresentationStore {
+declare class WorkingTreeStore {
+    private projectRoot;
+    private gitSync;
+    private logger?;
+    constructor(project: SemiontProject, logger?: Logger);
+    private shouldRunGit;
+    /**
+     * Write content to disk at the location indicated by storageUri.
+     *
+     * API/GUI/AI path: caller provides bytes; file may not yet exist.
+     *
+     * @param content - Raw bytes to write
+     * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
+     * @returns Stored resource metadata
+     */
+    store(content: Buffer, storageUri: string, options?: {
+        noGit?: boolean;
+    }): Promise<StoredResource>;
     /**
-     * Store content and return representation metadata
+     * Read an existing file and return its metadata.
+     *
+     * CLI path: the file is already on disk. We read it to compute the checksum.
+     * If expectedChecksum is provided, throws ChecksumMismatchError on mismatch.
      *
-     * @param content - Raw bytes to store
-     * @param metadata - Representation metadata
-     * @returns Complete representation info with checksum
+     * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
+     * @param expectedChecksum - Optional SHA-256 to verify against
+     * @returns Stored resource metadata
+     * @throws ChecksumMismatchError if expectedChecksum is provided and does not match
+     * @throws Error if file does not exist
      */
-    store(content: Buffer, metadata: RepresentationMetadata): Promise<StoredRepresentation>;
+    register(storageUri: string, expectedChecksum?: string, options?: {
+        noGit?: boolean;
+    }): Promise<StoredResource>;
     /**
-     * Retrieve content by checksum (content-addressed lookup)
+     * Read file content by URI.
      *
-     * @param checksum - Content checksum as raw hex (e.g., "5aaa0b72...")
-     * @param mediaType - MIME type (e.g., "text/markdown")
+     * @param storageUri - file:// URI
      * @returns Raw bytes
      */
-    retrieve(checksum: string, mediaType: string): Promise<Buffer>;
-}
-/**
- * Filesystem implementation of RepresentationStore
- */
-declare class FilesystemRepresentationStore implements RepresentationStore {
-    private basePath;
-    private logger?;
-    constructor(project: SemiontProject, logger?: Logger);
-    store(content: Buffer, metadata: RepresentationMetadata): Promise<StoredRepresentation>;
-    retrieve(checksum: string, mediaType: string): Promise<Buffer>;
+    retrieve(storageUri: string): Promise<Buffer>;
+    /**
+     * Move a file from one URI to another.
+     *
+     * If .git/ exists in the project root and noGit is not set, runs `git mv`.
+     * Otherwise (no .git/ or noGit: true), runs fs.rename.
+     *
+     * @param fromUri - Current file:// URI
+     * @param toUri - New file:// URI
+     * @param options.noGit - Skip git mv even if .git/ is present
+     */
+    move(fromUri: string, toUri: string, options?: {
+        noGit?: boolean;
+    }): Promise<void>;
     /**
-     * Encode media type for filesystem path
-     * Replaces "/" with "~1" to avoid directory separators
+     * Remove a file from the working tree.
+     *
+     * If .git/ exists and noGit is not set:
+     *   - keepFile false (default): runs `git rm` (removes from index and disk)
+     *   - keepFile true: runs `git rm --cached` (removes from index only, file stays on disk)
+     * If no .git/ or noGit: true:
+     *   - keepFile false: runs fs.unlink
+     *   - keepFile true: no-op on filesystem
      *
-     * @param mediaType - MIME type (e.g., "text/markdown")
-     * @returns Encoded path segment (e.g., "text~1markdown")
+     * @param storageUri - file:// URI
+     * @param options.noGit - Skip git rm even if .git/ is present
+     * @param options.keepFile - Remove from git index only; leave file on disk
      */
-    private encodeMediaType;
+    remove(storageUri: string, options?: {
+        noGit?: boolean;
+        keepFile?: boolean;
+    }): Promise<void>;
+    /**
+     * Convert a file:// URI to an absolute filesystem path.
+     *
+     * "file://docs/overview.md" → "{projectRoot}/docs/overview.md"
+     *
+     * @param storageUri - file:// URI
+     * @returns Absolute path
+     */
+    resolveUri(storageUri: string): string;
+}
+/**
+ * Thrown when a registered file's checksum does not match the expected value.
+ * This indicates the file on disk differs from what was recorded (e.g. modified
+ * after staging, or wrong file path provided).
+ */
+declare class ChecksumMismatchError extends Error {
+    readonly storageUri: string;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(storageUri: string, expected: string, actual: string);
 }
 
 /**
@@ -137,4 +171,4 @@ declare function calculateChecksum(content: string | Buffer): string;
  */
 declare function verifyChecksum(content: string | Buffer, checksum: string): boolean;
 
-export { FilesystemRepresentationStore, type RepresentationMetadata, type RepresentationStore, type StoredRepresentation, calculateChecksum, getExtensionForMimeType, hasKnownExtension, verifyChecksum };
+export { ChecksumMismatchError, type StoredResource, WorkingTreeStore, calculateChecksum, getExtensionForMimeType, hasKnownExtension, verifyChecksum };

package/dist/index.js

@@ -1,5 +1,6 @@
-// src/representation-store.ts
+// src/working-tree-store.ts
 import { promises as fs } from "fs";
+import { execFileSync } from "child_process";
 import path from "path";
 
 // src/checksum.ts
@@ -13,6 +14,184 @@ function verifyChecksum(content, checksum) {
   return calculateChecksum(content) === checksum;
 }
 
+// src/working-tree-store.ts
+var WorkingTreeStore = class {
+  projectRoot;
+  gitSync;
+  logger;
+  constructor(project, logger) {
+    this.projectRoot = project.root;
+    this.gitSync = project.gitSync;
+    this.logger = logger;
+  }
+  shouldRunGit(noGit) {
+    return this.gitSync && !noGit;
+  }
+  /**
+   * Write content to disk at the location indicated by storageUri.
+   *
+   * API/GUI/AI path: caller provides bytes; file may not yet exist.
+   *
+   * @param content - Raw bytes to write
+   * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
+   * @returns Stored resource metadata
+   */
+  async store(content, storageUri, options) {
+    const filePath = this.resolveUri(storageUri);
+    const checksum = calculateChecksum(content);
+    this.logger?.debug("Storing resource", { storageUri, byteSize: content.length });
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content);
+    if (this.shouldRunGit(options?.noGit)) {
+      execFileSync("git", ["add", filePath], { cwd: this.projectRoot });
+    }
+    this.logger?.info("Resource stored", { storageUri, checksum, byteSize: content.length });
+    return {
+      storageUri,
+      checksum,
+      byteSize: content.length,
+      created: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Read an existing file and return its metadata.
+   *
+   * CLI path: the file is already on disk. We read it to compute the checksum.
+   * If expectedChecksum is provided, throws ChecksumMismatchError on mismatch.
+   *
+   * @param storageUri - file:// URI (e.g. "file://docs/overview.md")
+   * @param expectedChecksum - Optional SHA-256 to verify against
+   * @returns Stored resource metadata
+   * @throws ChecksumMismatchError if expectedChecksum is provided and does not match
+   * @throws Error if file does not exist
+   */
+  async register(storageUri, expectedChecksum, options) {
+    const filePath = this.resolveUri(storageUri);
+    this.logger?.debug("Registering resource", { storageUri });
+    const content = await fs.readFile(filePath);
+    const checksum = calculateChecksum(content);
+    if (expectedChecksum !== void 0 && !verifyChecksum(content, expectedChecksum)) {
+      throw new ChecksumMismatchError(storageUri, expectedChecksum, checksum);
+    }
+    if (this.shouldRunGit(options?.noGit)) {
+      execFileSync("git", ["add", filePath], { cwd: this.projectRoot });
+    }
+    this.logger?.info("Resource registered", { storageUri, checksum, byteSize: content.length });
+    return {
+      storageUri,
+      checksum,
+      byteSize: content.length,
+      created: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Read file content by URI.
+   *
+   * @param storageUri - file:// URI
+   * @returns Raw bytes
+   */
+  async retrieve(storageUri) {
+    const filePath = this.resolveUri(storageUri);
+    try {
+      return await fs.readFile(filePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new Error(`Resource not found: ${storageUri}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Move a file from one URI to another.
+   *
+   * If .git/ exists in the project root and noGit is not set, runs `git mv`.
+   * Otherwise (no .git/ or noGit: true), runs fs.rename.
+   *
+   * @param fromUri - Current file:// URI
+   * @param toUri - New file:// URI
+   * @param options.noGit - Skip git mv even if .git/ is present
+   */
+  async move(fromUri, toUri, options) {
+    const fromPath = this.resolveUri(fromUri);
+    const toPath = this.resolveUri(toUri);
+    this.logger?.debug("Moving resource", { fromUri, toUri });
+    await fs.mkdir(path.dirname(toPath), { recursive: true });
+    if (this.shouldRunGit(options?.noGit)) {
+      execFileSync("git", ["mv", fromPath, toPath], { cwd: this.projectRoot });
+    } else {
+      await fs.rename(fromPath, toPath);
+    }
+    this.logger?.info("Resource moved", { fromUri, toUri });
+  }
+  /**
+   * Remove a file from the working tree.
+   *
+   * If .git/ exists and noGit is not set:
+   *   - keepFile false (default): runs `git rm` (removes from index and disk)
+   *   - keepFile true: runs `git rm --cached` (removes from index only, file stays on disk)
+   * If no .git/ or noGit: true:
+   *   - keepFile false: runs fs.unlink
+   *   - keepFile true: no-op on filesystem
+   *
+   * @param storageUri - file:// URI
+   * @param options.noGit - Skip git rm even if .git/ is present
+   * @param options.keepFile - Remove from git index only; leave file on disk
+   */
+  async remove(storageUri, options) {
+    const filePath = this.resolveUri(storageUri);
+    const keepFile = options?.keepFile ?? false;
+    this.logger?.debug("Removing resource", { storageUri, keepFile });
+    const useGit = this.shouldRunGit(options?.noGit);
+    if (useGit) {
+      const gitArgs = keepFile ? ["rm", "--cached", filePath] : ["rm", filePath];
+      execFileSync("git", gitArgs, { cwd: this.projectRoot });
+      this.logger?.info("Resource removed", { storageUri, keepFile, git: true });
+      return;
+    }
+    if (keepFile) {
+      this.logger?.info("Resource removed from index (file kept on disk)", { storageUri });
+      return;
+    }
+    try {
+      await fs.unlink(filePath);
+      this.logger?.info("Resource removed", { storageUri });
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        this.logger?.warn("Resource file already absent", { storageUri });
+        return;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Convert a file:// URI to an absolute filesystem path.
+   *
+   * "file://docs/overview.md" → "{projectRoot}/docs/overview.md"
+   *
+   * @param storageUri - file:// URI
+   * @returns Absolute path
+   */
+  resolveUri(storageUri) {
+    if (!storageUri.startsWith("file://")) {
+      throw new Error(`Invalid storage URI (must start with file://): ${storageUri}`);
+    }
+    const relativePath = storageUri.slice("file://".length);
+    return path.join(this.projectRoot, relativePath);
+  }
+};
+var ChecksumMismatchError = class extends Error {
+  constructor(storageUri, expected, actual) {
+    super(
+      `Checksum mismatch for ${storageUri}: expected ${expected.slice(0, 8)}... but got ${actual.slice(0, 8)}...
+The file on disk differs from the recorded checksum. Has it been modified since staging?`
+    );
+    this.storageUri = storageUri;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "ChecksumMismatchError";
+  }
+};
+
 // src/mime-extensions.ts
 var MIME_TO_EXTENSION = {
   // Text formats
@@ -98,115 +277,9 @@ function hasKnownExtension(mediaType) {
   const normalized = mediaType.toLowerCase().split(";")[0].trim();
   return normalized in MIME_TO_EXTENSION;
 }
-
-// src/representation-store.ts
-var FilesystemRepresentationStore = class {
-  basePath;
-  logger;
-  constructor(project, logger) {
-    this.logger = logger;
-    this.basePath = project.representationsDir;
-  }
-  async store(content, metadata) {
-    const checksum = calculateChecksum(content);
-    const baseMediaType = metadata.mediaType.split(";")[0].trim();
-    const mediaTypePath = this.encodeMediaType(baseMediaType);
-    const extension = getExtensionForMimeType(baseMediaType);
-    if (!checksum || checksum.length < 4) {
-      throw new Error(`Invalid checksum: ${checksum}`);
-    }
-    const ab = checksum.substring(0, 2);
-    const cd = checksum.substring(2, 4);
-    const filePath = path.join(
-      this.basePath,
-      mediaTypePath,
-      ab,
-      cd,
-      `rep-${checksum}${extension}`
-    );
-    this.logger?.debug("Storing representation", {
-      checksum,
-      mediaType: baseMediaType,
-      byteSize: content.length,
-      filename: metadata.filename
-    });
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, content);
-    this.logger?.info("Representation stored", {
-      checksum,
-      mediaType: baseMediaType,
-      byteSize: content.length,
-      path: filePath
-    });
-    return {
-      "@id": checksum,
-      // Use checksum as the ID (content-addressed)
-      ...metadata,
-      byteSize: content.length,
-      checksum,
-      created: (/* @__PURE__ */ new Date()).toISOString()
-    };
-  }
-  async retrieve(checksum, mediaType) {
-    const baseMediaType = mediaType.split(";")[0].trim();
-    const mediaTypePath = this.encodeMediaType(baseMediaType);
-    const extension = getExtensionForMimeType(baseMediaType);
-    if (!checksum || checksum.length < 4) {
-      throw new Error(`Invalid checksum: ${checksum}`);
-    }
-    const ab = checksum.substring(0, 2);
-    const cd = checksum.substring(2, 4);
-    const filePath = path.join(
-      this.basePath,
-      mediaTypePath,
-      ab,
-      cd,
-      `rep-${checksum}${extension}`
-    );
-    this.logger?.debug("Retrieving representation", {
-      checksum,
-      mediaType: baseMediaType
-    });
-    try {
-      const content = await fs.readFile(filePath);
-      this.logger?.info("Representation retrieved", {
-        checksum,
-        mediaType: baseMediaType,
-        byteSize: content.length,
-        path: filePath
-      });
-      return content;
-    } catch (error) {
-      if (error.code === "ENOENT") {
-        this.logger?.warn("Representation not found", {
-          checksum,
-          mediaType: baseMediaType,
-          path: filePath
-        });
-        throw new Error(`Representation not found for checksum ${checksum} with mediaType ${mediaType}`);
-      }
-      this.logger?.error("Failed to retrieve representation", {
-        checksum,
-        mediaType: baseMediaType,
-        error: error.message,
-        path: filePath
-      });
-      throw error;
-    }
-  }
-  /**
-   * Encode media type for filesystem path
-   * Replaces "/" with "~1" to avoid directory separators
-   *
-   * @param mediaType - MIME type (e.g., "text/markdown")
-   * @returns Encoded path segment (e.g., "text~1markdown")
-   */
-  encodeMediaType(mediaType) {
-    return mediaType.replace(/\//g, "~1");
-  }
-};
 export {
-  FilesystemRepresentationStore,
+  ChecksumMismatchError,
+  WorkingTreeStore,
   calculateChecksum,
   getExtensionForMimeType,
   hasKnownExtension,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/representation-store.ts","../src/checksum.ts","../src/mime-extensions.ts"],"sourcesContent":["/**\n * RepresentationStore - Content-addressed storage for byte-level resource representations\n *\n * Handles storage and retrieval of concrete byte-level renditions of resources.\n * Uses content-addressed storage where the checksum IS the filename.\n * Supports multiple storage backends (filesystem, S3, IPFS, etc.)\n *\n * Storage structure (filesystem):\n * basePath/representations/{mediaType}/{ab}/{cd}/rep-{checksum}{extension}\n *\n * Where:\n * - {mediaType} is base MIME type with \"/\" encoded as \"~1\" (e.g., \"text~1markdown\")\n * - {ab}/{cd} are first 4 hex digits of checksum for sharding\n * - {checksum} is the raw SHA-256 hex hash (e.g., \"5aaa0b72abc123...\")\n * - {extension} is derived from base MIME type (.md, .txt, .png, etc.)\n *\n * Example:\n * For content with checksum \"5aaa0b72abc123...\" and mediaType \"text/markdown; charset=iso-8859-1\":\n * - Storage path: basePath/representations/text~1markdown/5a/aa/rep-5aaa0b72abc123....md\n * - Stored mediaType: \"text/markdown; charset=iso-8859-1\" (full type with charset preserved)\n *\n * Character Encoding:\n * - Charset parameters in mediaType are preserved in metadata (e.g., \"text/plain; charset=iso-8859-1\")\n * - Storage path uses only base MIME type (strips charset for directory structure)\n * - Content stored as raw bytes - charset only affects decoding on retrieval\n *\n * This design provides:\n * - O(1) content retrieval by checksum + mediaType\n * - Automatic deduplication (identical content = same file)\n * - Idempotent storage operations\n * - Proper file extensions for filesystem browsing\n * - Faithful preservation of character encoding metadata\n */\n\nimport { promises as fs } from 'fs';\nimport path from 'path';\nimport type { SemiontProject } from '@semiont/core/node';\nimport type { Logger } from '@semiont/core';\nimport { calculateChecksum } from './checksum';\nimport { getExtensionForMimeType } from './mime-extensions';\n\n/**\n * Metadata for a representation being stored\n */\nexport interface RepresentationMetadata {\n  mediaType: string;        // REQUIRED - MIME type\n  filename?: string;\n  encoding?: string;\n  language?: string;\n  rel?: 'original' | 'thumbnail' | 'preview' | 'optimized' | 'derived' | 'other';\n}\n\n/**\n * Complete representation information\n */\nexport interface StoredRepresentation extends RepresentationMetadata {\n  '@id': string;           // Representation ID (same as checksum)\n  byteSize: number;        // Size in bytes\n  checksum: string;        // Raw SHA-256 hex hash\n  created: string;         // ISO 8601 timestamp\n}\n\n/**\n * Interface for representation storage backends\n */\nexport interface RepresentationStore {\n  /**\n   * Store content and return representation metadata\n   *\n   * @param content - Raw bytes to store\n   * @param metadata - Representation metadata\n   * @returns Complete representation info with checksum\n   */\n  store(content: Buffer, metadata: RepresentationMetadata): Promise<StoredRepresentation>;\n\n  /**\n   * Retrieve content by checksum (content-addressed lookup)\n   *\n   * @param checksum - Content checksum as raw hex (e.g., \"5aaa0b72...\")\n   * @param mediaType - MIME type (e.g., \"text/markdown\")\n   * @returns Raw bytes\n   */\n  retrieve(checksum: string, mediaType: string): Promise<Buffer>;\n}\n\n/**\n * Filesystem implementation of RepresentationStore\n */\nexport class FilesystemRepresentationStore implements RepresentationStore {\n  private basePath: string;\n  private logger?: Logger;\n\n  constructor(project: SemiontProject, logger?: Logger) {\n    this.logger = logger;\n    this.basePath = project.representationsDir;\n  }\n\n  async store(content: Buffer, metadata: RepresentationMetadata): Promise<StoredRepresentation> {\n    // Compute checksum (raw hex) - this will be used as the content address\n    const checksum = calculateChecksum(content);\n\n    // Strip charset/parameters for path - only use base MIME type for directory structure\n    // e.g., \"text/plain; charset=iso-8859-1\" -> \"text/plain\"\n    const baseMediaType = metadata.mediaType.split(';')[0]!.trim();\n    const mediaTypePath = this.encodeMediaType(baseMediaType);\n    const extension = getExtensionForMimeType(baseMediaType);\n\n    if (!checksum || checksum.length < 4) {\n      throw new Error(`Invalid checksum: ${checksum}`);\n    }\n\n    // Use first 4 hex digits for sharding: 5a/aa\n    const ab = checksum.substring(0, 2);\n    const cd = checksum.substring(2, 4);\n\n    // Build file path using raw hex checksum as filename with proper extension\n    const filePath = path.join(\n      this.basePath,\n      mediaTypePath,\n      ab,\n      cd,\n      `rep-${checksum}${extension}`\n    );\n\n    this.logger?.debug('Storing representation', {\n      checksum,\n      mediaType: baseMediaType,\n      byteSize: content.length,\n      filename: metadata.filename\n    });\n\n    // Create directory structure programmatically\n    await fs.mkdir(path.dirname(filePath), { recursive: true });\n\n    // Write content (idempotent - same content = same file)\n    await fs.writeFile(filePath, content);\n\n    this.logger?.info('Representation stored', {\n      checksum,\n      mediaType: baseMediaType,\n      byteSize: content.length,\n      path: filePath\n    });\n\n    return {\n      '@id': checksum, // Use checksum as the ID (content-addressed)\n      ...metadata,\n      byteSize: content.length,\n      checksum,\n      created: new Date().toISOString(),\n    };\n  }\n\n  async retrieve(checksum: string, mediaType: string): Promise<Buffer> {\n    // Strip charset/parameters for path - only use base MIME type for directory lookup\n    // e.g., \"text/plain; charset=iso-8859-1\" -> \"text/plain\"\n    const baseMediaType = mediaType.split(';')[0]!.trim();\n    const mediaTypePath = this.encodeMediaType(baseMediaType);\n    const extension = getExtensionForMimeType(baseMediaType);\n\n    if (!checksum || checksum.length < 4) {\n      throw new Error(`Invalid checksum: ${checksum}`);\n    }\n\n    // Use first 4 hex digits for sharding: 5a/aa\n    const ab = checksum.substring(0, 2);\n    const cd = checksum.substring(2, 4);\n\n    // Build file path from raw hex checksum with proper extension\n    const filePath = path.join(\n      this.basePath,\n      mediaTypePath,\n      ab,\n      cd,\n      `rep-${checksum}${extension}`\n    );\n\n    this.logger?.debug('Retrieving representation', {\n      checksum,\n      mediaType: baseMediaType\n    });\n\n    try {\n      const content = await fs.readFile(filePath);\n      this.logger?.info('Representation retrieved', {\n        checksum,\n        mediaType: baseMediaType,\n        byteSize: content.length,\n        path: filePath\n      });\n      return content;\n    } catch (error: any) {\n      if (error.code === 'ENOENT') {\n        this.logger?.warn('Representation not found', {\n          checksum,\n          mediaType: baseMediaType,\n          path: filePath\n        });\n        throw new Error(`Representation not found for checksum ${checksum} with mediaType ${mediaType}`);\n      }\n      this.logger?.error('Failed to retrieve representation', {\n        checksum,\n        mediaType: baseMediaType,\n        error: error.message,\n        path: filePath\n      });\n      throw error;\n    }\n  }\n\n  /**\n   * Encode media type for filesystem path\n   * Replaces \"/\" with \"~1\" to avoid directory separators\n   *\n   * @param mediaType - MIME type (e.g., \"text/markdown\")\n   * @returns Encoded path segment (e.g., \"text~1markdown\")\n   */\n  private encodeMediaType(mediaType: string): string {\n    return mediaType.replace(/\\//g, '~1');\n  }\n}\n","/**\n * Checksum utilities for content verification\n */\n\nimport { createHash } from 'crypto';\n\n/**\n * Calculate SHA-256 checksum of content\n * @param content The content to hash\n * @returns Hex-encoded SHA-256 hash\n */\nexport function calculateChecksum(content: string | Buffer): string {\n  const hash = createHash('sha256');\n  hash.update(content);\n  return hash.digest('hex');\n}\n\n/**\n * Verify content against a checksum\n * @param content The content to verify\n * @param checksum The expected checksum\n * @returns True if content matches checksum\n */\nexport function verifyChecksum(content: string | Buffer, checksum: string): boolean {\n  return calculateChecksum(content) === checksum;\n}\n","/**\n * MIME Type to File Extension Mapping\n *\n * Maps common MIME types to their standard file extensions.\n * Used by RepresentationStore to save files with proper extensions.\n */\n\n/**\n * Comprehensive MIME type to extension mapping\n */\nconst MIME_TO_EXTENSION: Record<string, string> = {\n  // Text formats\n  'text/plain': '.txt',\n  'text/markdown': '.md',\n  'text/html': '.html',\n  'text/css': '.css',\n  'text/csv': '.csv',\n  'text/xml': '.xml',\n\n  // Application formats - structured data\n  'application/json': '.json',\n  'application/xml': '.xml',\n  'application/yaml': '.yaml',\n  'application/x-yaml': '.yaml',\n\n  // Application formats - documents\n  'application/pdf': '.pdf',\n  'application/msword': '.doc',\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',\n  'application/vnd.ms-excel': '.xls',\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',\n  'application/vnd.ms-powerpoint': '.ppt',\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',\n\n  // Application formats - archives\n  'application/zip': '.zip',\n  'application/gzip': '.gz',\n  'application/x-tar': '.tar',\n  'application/x-7z-compressed': '.7z',\n\n  // Application formats - executables/binaries\n  'application/octet-stream': '.bin',\n  'application/wasm': '.wasm',\n\n  // Image formats\n  'image/png': '.png',\n  'image/jpeg': '.jpg',\n  'image/gif': '.gif',\n  'image/webp': '.webp',\n  'image/svg+xml': '.svg',\n  'image/bmp': '.bmp',\n  'image/tiff': '.tiff',\n  'image/x-icon': '.ico',\n\n  // Audio formats\n  'audio/mpeg': '.mp3',\n  'audio/wav': '.wav',\n  'audio/ogg': '.ogg',\n  'audio/webm': '.webm',\n  'audio/aac': '.aac',\n  'audio/flac': '.flac',\n\n  // Video formats\n  'video/mp4': '.mp4',\n  'video/mpeg': '.mpeg',\n  'video/webm': '.webm',\n  'video/ogg': '.ogv',\n  'video/quicktime': '.mov',\n  'video/x-msvideo': '.avi',\n\n  // Programming languages\n  'text/javascript': '.js',\n  'application/javascript': '.js',\n  'text/x-typescript': '.ts',\n  'application/typescript': '.ts',\n  'text/x-python': '.py',\n  'text/x-java': '.java',\n  'text/x-c': '.c',\n  'text/x-c++': '.cpp',\n  'text/x-csharp': '.cs',\n  'text/x-go': '.go',\n  'text/x-rust': '.rs',\n  'text/x-ruby': '.rb',\n  'text/x-php': '.php',\n  'text/x-swift': '.swift',\n  'text/x-kotlin': '.kt',\n  'text/x-shell': '.sh',\n\n  // Font formats\n  'font/woff': '.woff',\n  'font/woff2': '.woff2',\n  'font/ttf': '.ttf',\n  'font/otf': '.otf',\n};\n\n/**\n * Get file extension for a MIME type\n *\n * @param mediaType - MIME type (e.g., \"text/markdown\")\n * @returns File extension with leading dot (e.g., \".md\") or \".dat\" if unknown\n *\n * @example\n * getExtensionForMimeType('text/markdown') // => '.md'\n * getExtensionForMimeType('image/png')     // => '.png'\n * getExtensionForMimeType('unknown/type')  // => '.dat'\n */\nexport function getExtensionForMimeType(mediaType: string): string {\n  // Normalize MIME type (lowercase, remove parameters)\n  const normalized = mediaType.toLowerCase().split(';')[0]!.trim();\n\n  // Look up in mapping\n  const extension = MIME_TO_EXTENSION[normalized];\n\n  // Return mapped extension or fallback to .dat\n  return extension || '.dat';\n}\n\n/**\n * Check if a MIME type has a known extension mapping\n *\n * @param mediaType - MIME type to check\n * @returns true if extension is known, false if would fallback to .dat\n */\nexport function hasKnownExtension(mediaType: string): boolean {\n  const normalized = mediaType.toLowerCase().split(';')[0]!.trim();\n  return normalized in MIME_TO_EXTENSION;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/working-tree-store.ts","../src/checksum.ts","../src/mime-extensions.ts"],"sourcesContent":["/**\n * WorkingTreeStore - Manages files in the project working tree\n *\n * Unlike the old content-addressed RepresentationStore, this store treats\n * the working tree (project root) as the source of truth for file content.\n * Resources are identified by their file:// URI, which is stable across\n * content changes and moves (tracked by events).\n *\n * Two write paths:\n * - store(content, storageUri): Write bytes to disk (API/GUI/AI path).\n *   Used when the file does not yet exist and the caller provides content.\n * - register(storageUri, expectedChecksum?): Read an existing file and\n *   return its metadata (CLI path). The file is already on disk; we just\n *   verify and record it. If expectedChecksum is provided, throws on mismatch.\n *\n * Storage layout:\n *   {projectRoot}/{path-from-uri}\n *\n * For example, storageUri \"file://docs/overview.md\" resolves to\n *   {projectRoot}/docs/overview.md\n */\n\nimport { promises as fs } from 'fs';\nimport { execFileSync } from 'child_process';\nimport path from 'path';\nimport type { SemiontProject } from '@semiont/core/node';\nimport type { Logger } from '@semiont/core';\nimport { calculateChecksum, verifyChecksum } from './checksum';\n\n/**\n * Result of store() or register()\n */\nexport interface StoredResource {\n  storageUri: string;    // file:// URI (e.g. \"file://docs/overview.md\")\n  checksum: string;      // SHA-256 hex of content\n  byteSize: number;      // Size in bytes\n  created: string;       // ISO 8601 timestamp\n}\n\n/**\n * Manages files in the project working tree\n */\nexport class WorkingTreeStore {\n  private projectRoot: string;\n  private gitSync: boolean;\n  private logger?: Logger;\n\n  constructor(project: SemiontProject, logger?: Logger) {\n    this.projectRoot = project.root;\n    this.gitSync = project.gitSync;\n    this.logger = logger;\n  }\n\n  private shouldRunGit(noGit?: boolean): boolean {\n    return this.gitSync && !noGit;\n  }\n\n  /**\n   * Write content to disk at the location indicated by storageUri.\n   *\n   * API/GUI/AI path: caller provides bytes; file may not yet exist.\n   *\n   * @param content - Raw bytes to write\n   * @param storageUri - file:// URI (e.g. \"file://docs/overview.md\")\n   * @returns Stored resource metadata\n   */\n  async store(content: Buffer, storageUri: string, options?: { noGit?: boolean }): Promise<StoredResource> {\n    const filePath = this.resolveUri(storageUri);\n    const checksum = calculateChecksum(content);\n\n    this.logger?.debug('Storing resource', { storageUri, byteSize: content.length });\n\n    await fs.mkdir(path.dirname(filePath), { recursive: true });\n    await fs.writeFile(filePath, content);\n\n    if (this.shouldRunGit(options?.noGit)) {\n      execFileSync('git', ['add', filePath], { cwd: this.projectRoot });\n    }\n\n    this.logger?.info('Resource stored', { storageUri, checksum, byteSize: content.length });\n\n    return {\n      storageUri,\n      checksum,\n      byteSize: content.length,\n      created: new Date().toISOString(),\n    };\n  }\n\n  /**\n   * Read an existing file and return its metadata.\n   *\n   * CLI path: the file is already on disk. We read it to compute the checksum.\n   * If expectedChecksum is provided, throws ChecksumMismatchError on mismatch.\n   *\n   * @param storageUri - file:// URI (e.g. \"file://docs/overview.md\")\n   * @param expectedChecksum - Optional SHA-256 to verify against\n   * @returns Stored resource metadata\n   * @throws ChecksumMismatchError if expectedChecksum is provided and does not match\n   * @throws Error if file does not exist\n   */\n  async register(storageUri: string, expectedChecksum?: string, options?: { noGit?: boolean }): Promise<StoredResource> {\n    const filePath = this.resolveUri(storageUri);\n\n    this.logger?.debug('Registering resource', { storageUri });\n\n    const content = await fs.readFile(filePath);\n    const checksum = calculateChecksum(content);\n\n    if (expectedChecksum !== undefined && !verifyChecksum(content, expectedChecksum)) {\n      throw new ChecksumMismatchError(storageUri, expectedChecksum, checksum);\n    }\n\n    if (this.shouldRunGit(options?.noGit)) {\n      execFileSync('git', ['add', filePath], { cwd: this.projectRoot });\n    }\n\n    this.logger?.info('Resource registered', { storageUri, checksum, byteSize: content.length });\n\n    return {\n      storageUri,\n      checksum,\n      byteSize: content.length,\n      created: new Date().toISOString(),\n    };\n  }\n\n  /**\n   * Read file content by URI.\n   *\n   * @param storageUri - file:// URI\n   * @returns Raw bytes\n   */\n  async retrieve(storageUri: string): Promise<Buffer> {\n    const filePath = this.resolveUri(storageUri);\n    try {\n      return await fs.readFile(filePath);\n    } catch (error: any) {\n      if (error.code === 'ENOENT') {\n        throw new Error(`Resource not found: ${storageUri}`);\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Move a file from one URI to another.\n   *\n   * If .git/ exists in the project root and noGit is not set, runs `git mv`.\n   * Otherwise (no .git/ or noGit: true), runs fs.rename.\n   *\n   * @param fromUri - Current file:// URI\n   * @param toUri - New file:// URI\n   * @param options.noGit - Skip git mv even if .git/ is present\n   */\n  async move(fromUri: string, toUri: string, options?: { noGit?: boolean }): Promise<void> {\n    const fromPath = this.resolveUri(fromUri);\n    const toPath = this.resolveUri(toUri);\n\n    this.logger?.debug('Moving resource', { fromUri, toUri });\n\n    await fs.mkdir(path.dirname(toPath), { recursive: true });\n\n    if (this.shouldRunGit(options?.noGit)) {\n      // git mv handles both the filesystem rename and the index update\n      execFileSync('git', ['mv', fromPath, toPath], { cwd: this.projectRoot });\n    } else {\n      await fs.rename(fromPath, toPath);\n    }\n\n    this.logger?.info('Resource moved', { fromUri, toUri });\n  }\n\n  /**\n   * Remove a file from the working tree.\n   *\n   * If .git/ exists and noGit is not set:\n   *   - keepFile false (default): runs `git rm` (removes from index and disk)\n   *   - keepFile true: runs `git rm --cached` (removes from index only, file stays on disk)\n   * If no .git/ or noGit: true:\n   *   - keepFile false: runs fs.unlink\n   *   - keepFile true: no-op on filesystem\n   *\n   * @param storageUri - file:// URI\n   * @param options.noGit - Skip git rm even if .git/ is present\n   * @param options.keepFile - Remove from git index only; leave file on disk\n   */\n  async remove(storageUri: string, options?: { noGit?: boolean; keepFile?: boolean }): Promise<void> {\n    const filePath = this.resolveUri(storageUri);\n    const keepFile = options?.keepFile ?? false;\n\n    this.logger?.debug('Removing resource', { storageUri, keepFile });\n\n    const useGit = this.shouldRunGit(options?.noGit);\n\n    if (useGit) {\n      const gitArgs = keepFile\n        ? ['rm', '--cached', filePath]\n        : ['rm', filePath];\n      execFileSync('git', gitArgs, { cwd: this.projectRoot });\n      this.logger?.info('Resource removed', { storageUri, keepFile, git: true });\n      return;\n    }\n\n    if (keepFile) {\n      this.logger?.info('Resource removed from index (file kept on disk)', { storageUri });\n      return;\n    }\n\n    try {\n      await fs.unlink(filePath);\n      this.logger?.info('Resource removed', { storageUri });\n    } catch (error: any) {\n      if (error.code === 'ENOENT') {\n        this.logger?.warn('Resource file already absent', { storageUri });\n        return;\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Convert a file:// URI to an absolute filesystem path.\n   *\n   * \"file://docs/overview.md\" → \"{projectRoot}/docs/overview.md\"\n   *\n   * @param storageUri - file:// URI\n   * @returns Absolute path\n   */\n  resolveUri(storageUri: string): string {\n    if (!storageUri.startsWith('file://')) {\n      throw new Error(`Invalid storage URI (must start with file://): ${storageUri}`);\n    }\n    const relativePath = storageUri.slice('file://'.length);\n    return path.join(this.projectRoot, relativePath);\n  }\n}\n\n/**\n * Thrown when a registered file's checksum does not match the expected value.\n * This indicates the file on disk differs from what was recorded (e.g. modified\n * after staging, or wrong file path provided).\n */\nexport class ChecksumMismatchError extends Error {\n  constructor(\n    readonly storageUri: string,\n    readonly expected: string,\n    readonly actual: string,\n  ) {\n    super(\n      `Checksum mismatch for ${storageUri}: expected ${expected.slice(0, 8)}... but got ${actual.slice(0, 8)}...\\n` +\n      `The file on disk differs from the recorded checksum. Has it been modified since staging?`\n    );\n    this.name = 'ChecksumMismatchError';\n  }\n}\n","/**\n * Checksum utilities for content verification\n */\n\nimport { createHash } from 'crypto';\n\n/**\n * Calculate SHA-256 checksum of content\n * @param content The content to hash\n * @returns Hex-encoded SHA-256 hash\n */\nexport function calculateChecksum(content: string | Buffer): string {\n  const hash = createHash('sha256');\n  hash.update(content);\n  return hash.digest('hex');\n}\n\n/**\n * Verify content against a checksum\n * @param content The content to verify\n * @param checksum The expected checksum\n * @returns True if content matches checksum\n */\nexport function verifyChecksum(content: string | Buffer, checksum: string): boolean {\n  return calculateChecksum(content) === checksum;\n}\n","/**\n * MIME Type to File Extension Mapping\n *\n * Maps common MIME types to their standard file extensions.\n * Used by RepresentationStore to save files with proper extensions.\n */\n\n/**\n * Comprehensive MIME type to extension mapping\n */\nconst MIME_TO_EXTENSION: Record<string, string> = {\n  // Text formats\n  'text/plain': '.txt',\n  'text/markdown': '.md',\n  'text/html': '.html',\n  'text/css': '.css',\n  'text/csv': '.csv',\n  'text/xml': '.xml',\n\n  // Application formats - structured data\n  'application/json': '.json',\n  'application/xml': '.xml',\n  'application/yaml': '.yaml',\n  'application/x-yaml': '.yaml',\n\n  // Application formats - documents\n  'application/pdf': '.pdf',\n  'application/msword': '.doc',\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',\n  'application/vnd.ms-excel': '.xls',\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',\n  'application/vnd.ms-powerpoint': '.ppt',\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',\n\n  // Application formats - archives\n  'application/zip': '.zip',\n  'application/gzip': '.gz',\n  'application/x-tar': '.tar',\n  'application/x-7z-compressed': '.7z',\n\n  // Application formats - executables/binaries\n  'application/octet-stream': '.bin',\n  'application/wasm': '.wasm',\n\n  // Image formats\n  'image/png': '.png',\n  'image/jpeg': '.jpg',\n  'image/gif': '.gif',\n  'image/webp': '.webp',\n  'image/svg+xml': '.svg',\n  'image/bmp': '.bmp',\n  'image/tiff': '.tiff',\n  'image/x-icon': '.ico',\n\n  // Audio formats\n  'audio/mpeg': '.mp3',\n  'audio/wav': '.wav',\n  'audio/ogg': '.ogg',\n  'audio/webm': '.webm',\n  'audio/aac': '.aac',\n  'audio/flac': '.flac',\n\n  // Video formats\n  'video/mp4': '.mp4',\n  'video/mpeg': '.mpeg',\n  'video/webm': '.webm',\n  'video/ogg': '.ogv',\n  'video/quicktime': '.mov',\n  'video/x-msvideo': '.avi',\n\n  // Programming languages\n  'text/javascript': '.js',\n  'application/javascript': '.js',\n  'text/x-typescript': '.ts',\n  'application/typescript': '.ts',\n  'text/x-python': '.py',\n  'text/x-java': '.java',\n  'text/x-c': '.c',\n  'text/x-c++': '.cpp',\n  'text/x-csharp': '.cs',\n  'text/x-go': '.go',\n  'text/x-rust': '.rs',\n  'text/x-ruby': '.rb',\n  'text/x-php': '.php',\n  'text/x-swift': '.swift',\n  'text/x-kotlin': '.kt',\n  'text/x-shell': '.sh',\n\n  // Font formats\n  'font/woff': '.woff',\n  'font/woff2': '.woff2',\n  'font/ttf': '.ttf',\n  'font/otf': '.otf',\n};\n\n/**\n * Get file extension for a MIME type\n *\n * @param mediaType - MIME type (e.g., \"text/markdown\")\n * @returns File extension with leading dot (e.g., \".md\") or \".dat\" if unknown\n *\n * @example\n * getExtensionForMimeType('text/markdown') // => '.md'\n * getExtensionForMimeType('image/png')     // => '.png'\n * getExtensionForMimeType('unknown/type')  // => '.dat'\n */\nexport function getExtensionForMimeType(mediaType: string): string {\n  // Normalize MIME type (lowercase, remove parameters)\n  const normalized = mediaType.toLowerCase().split(';')[0]!.trim();\n\n  // Look up in mapping\n  const extension = MIME_TO_EXTENSION[normalized];\n\n  // Return mapped extension or fallback to .dat\n  return extension || '.dat';\n}\n\n/**\n * Check if a MIME type has a known extension mapping\n *\n * @param mediaType - MIME type to check\n * @returns true if extension is known, false if would fallback to .dat\n */\nexport function hasKnownExtension(mediaType: string): boolean {\n  const normalized = mediaType.toLowerCase().split(';')[0]!.trim();\n  return normalized in MIME_TO_EXTENSION;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/content",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "type": "module",
   "description": "Content-addressed storage for resource representations",
   "main": "./dist/index.js",