@sentropic/artifacts 0.2.5 → 0.2.7

package/dist/server/source-read.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { parseManifest } from '../codecs.js';
 import { ArtifactOperationError } from './failures.js';
+import { TEXT_MIME_RE } from './mime.js';
+import { API_GUIDE_REF } from './templates.js';
 /** Read author bytes only. Provenance never substitutes for a stored snapshot. */
 export async function readArtifactSource(ports, input) {
     await ports.authorize();
@@ -59,10 +61,23 @@ export async function readArtifactSource(ports, input) {
             createHash('sha256').update(bytes).digest('hex') !== file.digest.slice(7)) {
             throw new ArtifactOperationError('verification_failed');
         }
-        files.push({ ...file, bytes: Array.from(bytes) });
+        // Verified raw bytes are encoded for the wire: text mime types as UTF-8
+        // text, everything else (including non-UTF-8 "text") as base64. Never an
+        // integer array, which blows the tool-result budget on small pages.
+        let text;
+        if (TEXT_MIME_RE.test(file.mimeType)) {
+            try {
+                text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch { /* Not valid UTF-8: fall back to base64. */ }
+        }
+        files.push({ ...file, ...(text !== undefined
+                ? { text, encoding: 'utf8' }
+                : { base64: Buffer.from(bytes).toString('base64'), encoding: 'base64' }) });
     }
     const sourceRef = await ports.getSource(input.artifactId) ?? null;
     await ports.authorize();
     return { artifactId: input.artifactId, releaseId: release.releaseId, digest: manifest.digest,
-        manifest: release.manifest, files, sourceRef, ...ports.urls?.(input.artifactId, release.releaseId) };
+        manifest: release.manifest, files, sourceRef, guideRef: ports.guideRef ?? API_GUIDE_REF,
+        ...ports.urls?.(input.artifactId, release.releaseId) };
 }

package/dist/server/summary.d.ts

@@ -20,9 +20,7 @@ export declare function artifactSummary(input: {
         write: boolean;
         manage: boolean;
     };
-    icon?: string | null | undefined;
-    description?: string | undefined;
-    title?: string | undefined;
+    metadata?: import("./access.js").ArtifactMetadata | undefined;
     artifactId: string;
     bindingName: string | null;
     ownerId: string;
@@ -36,4 +34,7 @@ export declare function artifactSummary(input: {
     digest: string | null;
     stableUrl: string | null;
     pinnedUrl: string | null;
+    title: string;
+    description: string;
+    icon: string | null;
 };

package/dist/server/summary.js

@@ -9,9 +9,10 @@ export function artifactSummary(input) {
         createdAt: acl.createdAt ?? null, updatedAt: acl.updatedAt ?? null,
         currentReleaseId: current?.releaseId ?? null, digest: current ? parseManifest(current.manifest).digest ?? null : null,
         stableUrl: urls?.stableUrl ?? null, pinnedUrl: current ? urls?.pinnedUrl ?? null : null,
-        ...(acl.title === undefined ? {} : { title: acl.title }),
-        ...(acl.description === undefined ? {} : { description: acl.description }),
-        ...(acl.icon === undefined ? {} : { icon: acl.icon }),
+        title: acl.metadata?.title ?? acl.title ?? acl.bindingName ?? artifactId,
+        description: acl.metadata?.description ?? acl.description ?? '',
+        icon: acl.metadata?.icon !== undefined ? acl.metadata.icon : acl.icon ?? null,
+        ...(acl.metadata === undefined ? {} : { metadata: acl.metadata }),
         permissions: { read: evaluateAccess(acl, actorId, 'read', input.approved),
             source: evaluateAccess(acl, actorId, 'source', input.approved), write: owner, manage: owner } };
 }

package/dist/server/templates.d.ts

@@ -29,5 +29,10 @@ export interface TemplateCatalogPort {
 }
 export declare const DEFAULT_TEMPLATE_ID = "static-html";
 export declare const DEFAULT_API_GUIDE_VERSION = "v1";
+/** Wire reference returned by get_source instead of embedding the guide body. */
+export declare const API_GUIDE_REF: {
+    readonly tool: "artifacts_get_api_guide";
+    readonly version: "v1";
+};
 /** Generic in-package catalog; hosts override with approved local assets. */
 export declare function createDefaultTemplateCatalog(): TemplateCatalogPort;

package/dist/server/templates.js

@@ -9,6 +9,8 @@
  */
 export const DEFAULT_TEMPLATE_ID = 'static-html';
 export const DEFAULT_API_GUIDE_VERSION = 'v1';
+/** Wire reference returned by get_source instead of embedding the guide body. */
+export const API_GUIDE_REF = { tool: 'artifacts_get_api_guide', version: DEFAULT_API_GUIDE_VERSION };
 const INDEX_HTML = [
     '<!doctype html>',
     '<html lang="en">',
@@ -44,11 +46,36 @@ const GUIDE_V1 = [
     'Publish and share static web pages through the `artifacts_*` tools:',
     '',
     '- `artifacts_get_template` / `artifacts_get_api_guide`: start here.',
-    '- `artifacts_ensure`: resolve (or create) your private artifact view.',
-    '- `artifacts_publish`: publish inline files as a new release.',
+    '- `artifacts_ensure`: resolve (or create) your private artifact view;',
+    '  optional `title`, `description` and `icon` (one short word) describe it.',
+    '- `artifacts_publish`: publish inline `files` as a new release, or apply',
+    '  small `edits` (`[{path, oldStr, newStr}]`) to the current release\'s',
+    '  text files — `oldStr` must occur exactly once per file, otherwise the',
+    '  call fails with `edit_mismatch` and changes nothing. Both accept',
+    '  optional metadata and `expectedCurrentReleaseId`: when set and not the',
+    '  current release, the call fails with a `conflict` error carrying the',
+    '  current release id and digest so you can re-read and merge.',
+    '  Strict profiles require this field on publish and revert; null means unpublished.',
+    '  Edits target that observed release, with at most 100 ordered substitutions.',
+    '  Reuse the exact idempotency key after a lost response, including commitState unknown.',
+    '  Replays precede edits and CAS; changing metadata, edits or the precondition under',
+    '  the same key returns conflict with variant command_conflict.',
+    '  MCP returns the complete artifacts-outcome/v2 JSON envelope: ok, invocationId,',
+    '  commitState, replayed/output on success, or typed error details on failure.',
     '- `artifacts_create_upload` + bounded HTTP append +',
     '  `artifacts_commit_upload`: stage large bytes, then commit them.',
-    '- `artifacts_list` / `artifacts_get` / `artifacts_get_source`: discover.',
+    '- `artifacts_list` / `artifacts_get`: discover (metadata included).',
+    '- `artifacts_list_versions`: full release history of one artifact —',
+    '  per release: id, created at, author, state, whether it is current,',
+    '  and a content digest.',
+    '- `artifacts_get_source`: verified file contents of the current or a selected',
+    '  release, for editing. Text mime types come back as `text` with',
+    '  `encoding: "utf8"`; every other file as `base64` with `encoding: "base64"` —',
+    '  never an integer array. The result carries a `guideRef` (tool + version),',
+    '  never the guide body. Per call: at most 32 files and 256 KiB decoded.',
+    '- `artifacts_revert`: make an earlier release current again as a NEW',
+    '  release that copies its content — the artifact URL stays stable and',
+    '  history only grows. Purged releases are refused with `release_unavailable`.',
     '- `artifacts_fork`: private independent copy (no ACL copied).',
     '- `artifacts_set_access`: grant/revoke read or source, toggle public.',
     '- `artifacts_promote`: explicit version selection (expected-current).',

package/dist/server/versions.d.ts

@@ -0,0 +1,29 @@
+import type { ReleaseRecord } from './publication.js';
+/** A cursor fixes the release boundary and is bound to the authorized artifact and scope. */
+export declare function artifactVersions(input: {
+    artifactId: string;
+    storageScopeId: string;
+    currentReleaseId: string | null;
+    releases: ReleaseRecord[];
+    limit?: number;
+    cursor?: string;
+    state(releaseId: string): Promise<string>;
+    urls?: (artifactId: string, releaseId: string) => {
+        pinnedUrl: string;
+    };
+}): Promise<{
+    artifactId: string;
+    currentReleaseId: string | null;
+    versions: {
+        releaseId: string;
+        createdAt: string;
+        state: string;
+        authorPrincipalId: string | null;
+        parentReleaseId: string | null;
+        revertedFromReleaseId: string | null;
+        digest: string;
+        isCurrent: boolean;
+        pinnedUrl: string | null;
+    }[];
+    nextCursor: string | null;
+}>;

package/dist/server/versions.js

@@ -0,0 +1,39 @@
+import { ArtifactOperationError } from './failures.js';
+const order = (a, b) => a.createdAt.localeCompare(b.createdAt) || a.releaseId.localeCompare(b.releaseId);
+/** A cursor fixes the release boundary and is bound to the authorized artifact and scope. */
+export async function artifactVersions(input) {
+    const releases = [...input.releases].sort((a, b) => order(b, a));
+    let snapshot = releases[0];
+    let after;
+    if (input.cursor !== undefined) {
+        try {
+            const parsed = JSON.parse(Buffer.from(input.cursor, 'base64url').toString('utf8'));
+            const position = (value) => value && typeof value.createdAt === 'string' &&
+                typeof value.releaseId === 'string' && releases.some(release => order(release, value) === 0);
+            if (parsed.artifactId !== input.artifactId || parsed.storageScopeId !== input.storageScopeId ||
+                !position(parsed.snapshot) || !position(parsed.after) || order(parsed.after, parsed.snapshot) > 0)
+                throw new Error();
+            snapshot = parsed.snapshot;
+            after = parsed.after;
+        }
+        catch {
+            throw new ArtifactOperationError('invalid_request');
+        }
+    }
+    const available = releases.filter(release => snapshot && order(release, snapshot) <= 0 &&
+        (!after || order(release, after) < 0));
+    const page = available.slice(0, input.limit ?? 20);
+    const versions = await Promise.all(page.map(async (release) => {
+        const state = await input.state(release.releaseId);
+        return { releaseId: release.releaseId, createdAt: release.createdAt, state,
+            authorPrincipalId: release.authorPrincipalId ?? null, parentReleaseId: release.parentReleaseId ?? null,
+            revertedFromReleaseId: release.revertedFromReleaseId ?? null, digest: release.manifestDigest,
+            isCurrent: release.releaseId === input.currentReleaseId,
+            pinnedUrl: state === 'purged' ? null : input.urls?.(input.artifactId, release.releaseId).pinnedUrl ?? null };
+    }));
+    const last = page.at(-1);
+    const position = (value) => ({ createdAt: value.createdAt, releaseId: value.releaseId });
+    return { artifactId: input.artifactId, currentReleaseId: input.currentReleaseId, versions,
+        nextCursor: last && available.length > page.length ? Buffer.from(JSON.stringify({ artifactId: input.artifactId,
+            storageScopeId: input.storageScopeId, snapshot: position(snapshot), after: position(last) })).toString('base64url') : null };
+}

package/docs/migration-l6.md

@@ -108,7 +108,14 @@ claim completion. Do not pass a raw pool to transaction-scoped deletion claims.
 ## Durable state and failures
 
 Stop old writers before enabling the new composition. Apply migrations
-`0001_artifacts.sql`, `0002_lifecycle.sql` and additive `0003_coordinator.sql`.
+`0001_artifacts.sql`, `0002_lifecycle.sql`, additive `0003_coordinator.sql`,
+`0004_terminal_controls.sql`, and `0005_metadata.sql` (metadata and release lineage).
+Preserve the existing host journal prefix, including activation assets, on upgrades.
+
+R2 bindings explicitly select `profileRevisionId`, `requireExpectedCurrentReleaseId`
+and `resultEnvelopeVersion`. The compatible p0b profile keeps full-bundle publication
+and root results. The CAS switchover can keep result version 1; activate part 1 only
+after qualification of result version 2. IMMO owns both switchovers and activation.
 Preserve historical rows and objects. Supply `legacyRecords`, using
 `createPostgresLegacyArtifactRecords(pool)` for PostgreSQL. An empty inventory
 reader is appropriate only for a verified fresh store.

package/migrations/0005_metadata.sql

@@ -0,0 +1,14 @@
+-- Parity P0 — artifact display metadata (title/description/icon).
+--
+-- Additive upgrade after 0004_terminal_controls: no column is dropped or narrowed, existing
+-- rows keep working (default '{}' preserves "no metadata" semantics). The host
+-- applies this file through its existing migration journal.
+
+ALTER TABLE artifacts.artifacts
+  ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'::jsonb;
+
+-- Historical authors and lineage remain unknown; populate these on new commits only.
+ALTER TABLE artifacts.releases
+  ADD COLUMN IF NOT EXISTS author_principal_id TEXT,
+  ADD COLUMN IF NOT EXISTS parent_release_id UUID,
+  ADD COLUMN IF NOT EXISTS reverted_from_release_id UUID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9).",
   "type": "module",
   "license": "MIT",
@@ -208,7 +208,7 @@
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.980.0",
-    "@sentropic/mcp-platform": ">=0.3.0 <0.5.0",
+    "@sentropic/mcp-platform": ">=0.4.1 <0.5.0",
     "pg": "^8.12.0"
   },
   "peerDependenciesMeta": {