relic-mcp 0.3.0 → 0.3.2

package/src/publish.ts

@@ -21,7 +21,12 @@ import {
   type RendererClass,
   relicUrl,
 } from '@relic/format';
-import { savePublishState } from './state.ts';
+import {
+  loadPublishedSource,
+  resolveSourceIdentity,
+  type SourceIdentity,
+  savePublishState,
+} from './state.ts';
 
 /**
  * Codes for the legs the app server is not in.
@@ -37,6 +42,7 @@ export type ClientCode =
   | 'source_is_directory'
   | 'source_not_regular_file'
   | 'source_unreadable'
+  | 'source_already_published'
   | 'local_size_precheck_failed'
   | 'upload_failed'
   | 'service_unreachable'
@@ -96,6 +102,11 @@ export interface PublishInput {
    * to survive the wire.
    */
   readonly ttl_days?: number | undefined;
+  /**
+   * Bypass prior-publish refusal only when a second independent URL is
+   * intentional. False and undefined both preserve the existing URL.
+   */
+  readonly force_new?: boolean | undefined;
 }
 
 export interface PublishResult {
@@ -121,15 +132,117 @@ export interface PublishDeps {
   readonly files: FileReader;
   readonly fetch: typeof globalThis.fetch;
   readonly clientName: string;
+  /** Test seam for a filesystem that does not exist outside memory. */
+  readonly identifySource?: (path: string) => Promise<SourceIdentity>;
   /** Retries on a colliding ID, which format.md 1.4 obliges the client to do. */
   readonly maxCollisionRetries?: number;
 }
 
+export interface RepublishToolCall {
+  readonly name: 'relic_republish';
+  readonly arguments: {
+    readonly relic_id: string;
+    readonly path: string;
+  };
+}
+
+export interface PriorPublish {
+  readonly relic_id: string;
+  readonly version: number;
+  readonly source: SourceIdentity;
+}
+
+export interface PublishedSourceLookup {
+  readonly resolved_path: string;
+  readonly source: SourceIdentity;
+  readonly match?: PriorPublish | undefined;
+}
+
+/** The complete call an agent can make without retaining an earlier session. */
+export function republishToolCall(
+  relicId: string,
+  path: string
+): RepublishToolCall {
+  return {
+    name: 'relic_republish',
+    arguments: { relic_id: relicId, path },
+  };
+}
+
+async function lookupResolvedSource(
+  resolvedPath: string,
+  deps: PublishDeps
+): Promise<PublishedSourceLookup> {
+  let source: SourceIdentity;
+  try {
+    source = await (deps.identifySource ?? resolveSourceIdentity)(resolvedPath);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    throw new PublishError(
+      code === 'ENOENT' ? 'source_not_found' : 'source_unreadable',
+      `could not resolve source identity for ${resolvedPath}: ` +
+        (error as Error).message,
+      { path: resolvedPath }
+    );
+  }
+
+  try {
+    const published = await loadPublishedSource(source);
+    return {
+      resolved_path: resolvedPath,
+      source,
+      ...(published === undefined
+        ? {}
+        : {
+            match: {
+              relic_id: published.relic_id,
+              version: published.state.version,
+              source: published.source,
+            },
+          }),
+    };
+  } catch (error) {
+    throw new PublishError('local_state_unreadable', (error as Error).message);
+  }
+}
+
+/** Look up a path in local state without reading its bytes or calling a server. */
+export async function lookupPublishedSource(
+  path: string,
+  deps: PublishDeps
+): Promise<PublishedSourceLookup> {
+  return lookupResolvedSource(deps.files.resolve(path), deps);
+}
+
 export async function publish(
   input: PublishInput,
   deps: PublishDeps
 ): Promise<PublishResult> {
   const source = await readSource(input.path, deps.files);
+  const sourceLookup = await lookupResolvedSource(source.resolvedPath, deps);
+  if (sourceLookup.match !== undefined && input.force_new !== true) {
+    const match = sourceLookup.match;
+    const republishCall = republishToolCall(
+      match.relic_id,
+      source.resolvedPath
+    );
+    const cost = 'a second URL that nobody holding the first one will ever see';
+    throw new PublishError(
+      'source_already_published',
+      `${match.source.description} is already version ${match.version} of ` +
+        `relic ${match.relic_id}. Publishing it as new would cost ${cost}. ` +
+        `Call relic_republish(${JSON.stringify(republishCall.arguments)}) ` +
+        'instead. Set force_new to true only when you intend a separate relic.',
+      {
+        relic_id: match.relic_id,
+        version: match.version,
+        source_identity: match.source.identity,
+        source_description: match.source.description,
+        cost,
+        republish_call: republishCall,
+      }
+    );
+  }
 
   // 1. Challenge. This returns the cap before a grant is requested, so the
   //    precheck below uses a number that came from the server moments ago
@@ -243,6 +356,7 @@ export async function publish(
         key: encodeKey(key),
         publish_token: publishToken,
         version: 1,
+        source: sourceLookup.source,
       });
     } catch (error) {
       // The relic itself is live and the URL works, so both are handed over

package/src/server.ts

@@ -33,9 +33,11 @@ import {
   unsupportedVersionError,
 } from './protocol.ts';
 import {
+  lookupPublishedSource,
   type PublishDeps,
   PublishError,
   publish,
+  republishToolCall,
   ServerRefusal,
 } from './publish.ts';
 import { republish } from './republish.ts';
@@ -86,6 +88,15 @@ export const DESCRIBE_TOOL_NAME = 'relic_describe_client';
  */
 export const REPUBLISH_TOOL_NAME = 'relic_republish';
 
+/**
+ * Source lookup is a separate read-only tool.
+ *
+ * An agent needs the id before it chooses publish or republish, and a lookup
+ * hidden inside either write tool would only be observable after choosing the
+ * wrong one. This call reads local state and never contacts the service.
+ */
+export const LOOKUP_TOOL_NAME = 'relic_lookup_source';
+
 /**
  * The ceiling on a publisher-supplied lifetime, matching the grant
  * contract's `maxTtlDays`. Refusing here keeps a typo like 36500 from
@@ -98,9 +109,12 @@ export const TOOL_DEFINITION = {
   name: TOOL_NAME,
   title: 'Publish a relic',
   description:
-    'Encrypt a file on this machine and publish it as a relic, returning a ' +
-    'shareable URL. The encryption key is generated locally and never sent ' +
-    'to the service. Takes a filesystem path, never inline content.',
+    'Encrypt a file on this machine and publish it as a new relic, returning ' +
+    'a shareable URL. Publishing an update this way costs a second URL that ' +
+    'nobody holding the first one will ever see; use relic_republish instead ' +
+    'so the existing URL keeps working. The encryption key is generated ' +
+    'locally and never sent to the service. Takes a filesystem path, never ' +
+    'inline content.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -123,6 +137,14 @@ export const TOOL_DEFINITION = {
           'relic is kept until it is deleted. Shorter is better for ' +
           'sensitive content.',
       },
+      force_new: {
+        type: 'boolean',
+        default: false,
+        description:
+          'Optional. Publish a deliberately separate relic even when this ' +
+          'machine already published the same source. Defaults to false. Use ' +
+          'only when you want two independent URLs for one file.',
+      },
     },
     required: ['path'],
     additionalProperties: false,
@@ -228,6 +250,64 @@ export const REPUBLISH_TOOL_DEFINITION = {
   },
 } as const;
 
+export const LOOKUP_TOOL_DEFINITION = {
+  name: LOOKUP_TOOL_NAME,
+  title: 'Look up a published source',
+  description:
+    'Look up whether this machine already published a file and return the ' +
+    'relic id needed by relic_republish. Reads local publish state only and ' +
+    'never calls the service.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Filesystem path to the source to look up.',
+      },
+    },
+    required: ['path'],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      found: { type: 'boolean' },
+      relic_id: { type: ['string', 'null'] },
+      version: { type: ['integer', 'null'], minimum: 1 },
+      resolved_path: { type: 'string' },
+      source_identity: { type: 'string' },
+      source_description: { type: 'string' },
+      republish_call: {
+        type: ['object', 'null'],
+        properties: {
+          name: { type: 'string', const: REPUBLISH_TOOL_NAME },
+          arguments: {
+            type: 'object',
+            properties: {
+              relic_id: { type: 'string' },
+              path: { type: 'string' },
+            },
+            required: ['relic_id', 'path'],
+            additionalProperties: false,
+          },
+        },
+        required: ['name', 'arguments'],
+        additionalProperties: false,
+      },
+    },
+    required: [
+      'found',
+      'relic_id',
+      'version',
+      'resolved_path',
+      'source_identity',
+      'source_description',
+      'republish_call',
+    ],
+    additionalProperties: false,
+  },
+} as const;
+
 export const DESCRIBE_TOOL_DEFINITION = {
   name: DESCRIBE_TOOL_NAME,
   title: 'Describe the Relic client',
@@ -262,6 +342,44 @@ export const SERVER_INFO = {
 
 export const CAPABILITIES = { tools: {} } as const;
 
+/**
+ * Server-level guidance, returned on the handshake so a client can put it in
+ * the model's context before any tool is called.
+ *
+ * The plugin ships a skill with the same facts, but a skill only reaches
+ * Claude Code, and only when somebody installs the plugin rather than wiring
+ * this server directly. Every other client saw tool descriptions and nothing
+ * else, which left five things an agent cannot read off a schema.
+ *
+ * Item five is the reason this exists at all rather than living only in the
+ * publish result. The result is returned after the file is written, which is
+ * too late for an agent that already linked a stylesheet from a CDN. This
+ * lands before generation, which is the only moment the advice can be taken.
+ *
+ * It costs context on every session, so it stays short and it stays true.
+ * Anything that needs a paragraph belongs in the skill or the disclosure.
+ */
+export const INSTRUCTIONS = `Relic encrypts a file on this machine and uploads \
+only ciphertext. The key lives in the URL fragment, which browsers never send \
+to a server.
+
+Five things that change how you should act:
+
+1. The link is the credential. Anyone holding it, fragment included, can read \
+the file. Do not paste it into a tracker, a log, or a public channel.
+2. Publishing puts the key in this transcript. That is structural rather than \
+a defect, and worth saying plainly when you hand the link over.
+3. If a source was published before, use relic_republish so its URL keeps \
+working. Publishing it as new costs a second URL that nobody holding the first \
+one will ever see. relic_publish refuses by default, relic_lookup_source \
+recovers the id, and force_new is only for a deliberate second link.
+4. A relic can be republished only from the machine that published it, which \
+is where its key and publish token are stored. Anywhere else it refuses, and \
+no retry changes that.
+5. Rendered HTML and JSX run in an isolated frame with no network access. \
+Inline the styles, scripts, fonts, and images a page needs, because a CDN \
+reference renders as nothing. Decide that before you write the file.`;
+
 /**
  * Handle one JSON-RPC message.
  *
@@ -297,6 +415,7 @@ export async function handleMessage(
           protocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
           capabilities: CAPABILITIES,
           serverInfo: SERVER_INFO,
+          instructions: INSTRUCTIONS,
         },
       };
 
@@ -312,6 +431,7 @@ export async function handleMessage(
           protocolVersion: isSupportedVersion(asked) ? asked : PROTOCOL_VERSION,
           capabilities: CAPABILITIES,
           serverInfo: SERVER_INFO,
+          instructions: INSTRUCTIONS,
         },
       };
     }
@@ -326,6 +446,7 @@ export async function handleMessage(
         result: {
           tools: [
             TOOL_DEFINITION,
+            LOOKUP_TOOL_DEFINITION,
             REPUBLISH_TOOL_DEFINITION,
             DESCRIBE_TOOL_DEFINITION,
           ],
@@ -382,8 +503,9 @@ async function callTool(
           plaintext_transmitted_to_service: false,
           ciphertext_destination: 'object storage, via a signed URL',
           local_publish_state:
-            'relic id, key, and publish token per relic, written 0600 under ' +
-            'the user config directory; never printed, never sent',
+            'relic id, source identity, key, and publish token per relic, ' +
+            'written 0600 under the user config directory; key and token ' +
+            'are never printed or sent',
           service_origin: deps.serviceOrigin,
         },
         isError: false,
@@ -391,6 +513,10 @@ async function callTool(
     };
   }
 
+  if (params['name'] === LOOKUP_TOOL_NAME) {
+    return callLookup(id, params, deps);
+  }
+
   if (params['name'] === REPUBLISH_TOOL_NAME) {
     return callRepublish(id, params, deps);
   }
@@ -426,9 +552,23 @@ async function callTool(
     );
   }
 
+  const forceNew = args['force_new'];
+  if (forceNew !== undefined && typeof forceNew !== 'boolean') {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      '`force_new` must be a boolean or omitted'
+    );
+  }
+
   try {
     const result = await publish(
-      { path, filename, ttl_days: ttlDays.days },
+      {
+        path,
+        filename,
+        ttl_days: ttlDays.days,
+        force_new: forceNew === true,
+      },
       deps
     );
     return {
@@ -471,6 +611,63 @@ async function callTool(
   }
 }
 
+async function callLookup(
+  id: string | number | null,
+  params: Record<string, unknown>,
+  deps: PublishDeps
+): Promise<JsonRpcResponse> {
+  const args = (params['arguments'] ?? {}) as Record<string, unknown>;
+  const path = args['path'];
+  if (typeof path !== 'string' || path.length === 0) {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      '`path` is required and must be a string'
+    );
+  }
+
+  try {
+    const lookup = await lookupPublishedSource(path, deps);
+    const match = lookup.match;
+    const republishCall =
+      match === undefined
+        ? null
+        : republishToolCall(match.relic_id, lookup.resolved_path);
+    const structuredContent = {
+      found: match !== undefined,
+      relic_id: match?.relic_id ?? null,
+      version: match?.version ?? null,
+      resolved_path: lookup.resolved_path,
+      source_identity: lookup.source.identity,
+      source_description: lookup.source.description,
+      republish_call: republishCall,
+    };
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        content: [
+          {
+            type: 'text',
+            text:
+              match === undefined
+                ? `No prior relic is recorded for ${lookup.source.description}.`
+                : `Found ${lookup.source.description} as version ` +
+                  `${match.version} of relic ${match.relic_id}.\n` +
+                  `Call relic_republish(${JSON.stringify(
+                    republishCall?.arguments
+                  )}).`,
+          },
+        ],
+        structuredContent,
+        isError: false,
+      },
+    };
+  } catch (error) {
+    return { jsonrpc: '2.0', id, result: toolError(error) };
+  }
+}
+
 async function callRepublish(
   id: string | number | null,
   params: Record<string, unknown>,
@@ -655,13 +852,14 @@ What the service operator can see: that a relic exists, roughly how big it is,
 what coarse class it was declared as, the publishing IP, and when it was
 fetched. Never the contents, and never the key.
 
-What this keeps on disk: for each relic you publish, its id, its key, and a
-publish token, in a 0600 file under your user config directory. That record
-is what lets a relic be republished later, and it is why republishing works
+What this keeps on disk: for each relic you publish, its id, source identity,
+key, and publish token, in a 0600 file under your user config directory. The
+source index lets a fresh session find the id for relic_republish. The key and
+token let that republish keep the same URL, and they are why republishing works
 only on the machine that published. The token's SHA-256 is the only copy the
-service ever holds, and neither secret is ever printed or logged. Deleting
-the file changes nothing for existing links; it only ends this machine's
-ability to update those relics.
+service ever holds, and neither secret is ever printed or logged. Deleting the
+file changes nothing for existing links; it only ends this machine's ability
+to update those relics.
 
 What this does NOT protect against: the key is returned to your agent in the
 URL, so it enters the model's context and your session transcript. That is