c64bridge 0.8.1 → 0.9.1

package/scripts/update-readme.ts

@@ -142,6 +142,8 @@ type GroupedOperation = {
   readonly op: string;
   readonly description: string;
   readonly required: readonly string[];
+  readonly optional: readonly string[];
+  readonly properties: Readonly<Record<string, JsonSchema | undefined>>;
   readonly notes: readonly string[];
 };
 
@@ -165,20 +167,91 @@ function toTableValue(values: readonly string[]): string {
   return values.join(", ");
 }
 
+function formatInputName(name: string, schema?: JsonSchema): string {
+  const defaultSuffix = schema && Object.prototype.hasOwnProperty.call(schema, "default")
+    ? `=${JSON.stringify(schema.default)}`
+    : "";
+  return `\`${name}${defaultSuffix}\``;
+}
+
+function formatInputs(names: readonly string[], properties: Readonly<Record<string, JsonSchema | undefined>>): string {
+  return toTableValue(names.map((name) => formatInputName(name, properties[name])));
+}
+
 function collectGroupedOperations(schema?: JsonSchema): readonly GroupedOperation[] {
   if (!schema || !isObject(schema)) {
     return [];
   }
 
+  const metadataOperations = collectFromOperationMetadata(schema);
+  if (metadataOperations.length > 0) {
+    return metadataOperations;
+  }
+
   const discriminator = (schema as JsonSchema & { discriminator?: { propertyName?: string } }).discriminator;
   const variants = (schema as JsonSchema & { oneOf?: readonly JsonSchema[] }).oneOf;
 
-  if (!discriminator || discriminator.propertyName !== "op" || !Array.isArray(variants)) {
+  if (discriminator && discriminator.propertyName === "op" && Array.isArray(variants)) {
+    return collectFromVariantList(variants);
+  }
+
+  return collectFromFlattenedSchema(schema);
+}
+
+function collectFromOperationMetadata(schema: JsonSchema): readonly GroupedOperation[] {
+  const metadata = (schema as JsonSchema & {
+    readonly "x-c64bridge-operations"?: readonly unknown[];
+  })["x-c64bridge-operations"];
+
+  if (!Array.isArray(metadata)) {
     return [];
   }
 
   const operations: GroupedOperation[] = [];
 
+  for (const entry of metadata) {
+    if (!isObject(entry)) {
+      continue;
+    }
+
+    const opName = getString(entry.op);
+    if (!opName) {
+      continue;
+    }
+
+    const inputSchema = isObject(entry.inputSchema) ? (entry.inputSchema as JsonSchema) : undefined;
+    const properties = (inputSchema?.properties ?? {}) as Record<string, JsonSchema | undefined>;
+    const requiredProps = Array.isArray(entry.required)
+      ? entry.required.filter((name): name is string => typeof name === "string" && name !== "op")
+      : [];
+    const optionalProps = Array.isArray(entry.optional)
+      ? entry.optional.filter((name): name is string => typeof name === "string" && name !== "op")
+      : Object.keys(properties).filter((name) => name !== "op" && !requiredProps.includes(name));
+
+    const notes: string[] = [];
+    const hasVerificationProperty = Object.keys(properties).some((name) =>
+      name.toLowerCase().startsWith("verify"),
+    );
+    if (hasVerificationProperty) {
+      notes.push("supports verify");
+    }
+
+    operations.push({
+      op: opName,
+      description: getString(entry.description, `Operation ${opName}`),
+      required: requiredProps,
+      optional: optionalProps,
+      properties,
+      notes,
+    });
+  }
+
+  return operations;
+}
+
+function collectFromVariantList(variants: readonly JsonSchema[]): readonly GroupedOperation[] {
+  const operations: GroupedOperation[] = [];
+
   for (const variant of variants) {
     if (!variant || !isObject(variant)) {
       continue;
@@ -220,6 +293,8 @@ function collectGroupedOperations(schema?: JsonSchema): readonly GroupedOperatio
       op: opName,
       description,
       required: requiredProps,
+      optional: Object.keys(properties).filter((name) => name !== "op" && !requiredProps.includes(name)),
+      properties,
       notes,
     });
   }
@@ -227,6 +302,56 @@ function collectGroupedOperations(schema?: JsonSchema): readonly GroupedOperatio
   return operations;
 }
 
+function collectFromFlattenedSchema(schema: JsonSchema): readonly GroupedOperation[] {
+  const properties = (schema.properties ?? {}) as Record<string, JsonSchema | undefined>;
+  const opSchema = properties.op;
+  if (!opSchema || !isObject(opSchema)) {
+    return [];
+  }
+
+  const enumValues = (opSchema as JsonSchema).enum;
+  if (!Array.isArray(enumValues) || enumValues.length === 0) {
+    return [];
+  }
+
+  const opNames = enumValues.filter((value): value is string => typeof value === "string" && value.length > 0);
+  if (opNames.length === 0) {
+    return [];
+  }
+
+  const descriptionMap = parseOperationDescriptions(getString(schema.description));
+  const hasVerificationProperty = Object.keys(properties).some((name) =>
+    name !== "op" && name.toLowerCase().startsWith("verify"),
+  );
+  const notes = hasVerificationProperty ? ["supports verify"] : [];
+
+  return opNames.map((opName) => ({
+    op: opName,
+    description: descriptionMap.get(opName) ?? `Operation ${opName}`,
+    required: [] as readonly string[],
+    optional: Object.keys(properties).filter((name) => name !== "op"),
+    properties,
+    notes,
+  }));
+}
+
+function parseOperationDescriptions(description: string): Map<string, string> {
+  const result = new Map<string, string>();
+  if (!description) {
+    return result;
+  }
+
+  const lines = description.split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^\s*-\s+([A-Za-z0-9_]+):\s*(.+)$/);
+    if (match) {
+      result.set(match[1], match[2].trim());
+    }
+  }
+
+  return result;
+}
+
 export function renderToolsSection(modules: readonly ToolModuleDescriptor[] = describeToolModules()): string[] {
   const lines: string[] = ["### Tools", ""];
   const groupedTools: GroupedToolInfo[] = [];
@@ -250,6 +375,9 @@ export function renderToolsSection(modules: readonly ToolModuleDescriptor[] = de
       if (operations.length === 0) {
         lines.push("_No operations defined._");
       } else {
+        if (!lines.includes("_Address range convention: `address` + `length` means start address plus byte count; `startAddress` + `endAddress` means inclusive bounds._")) {
+          lines.splice(2, 0, "_Address range convention: `address` + `length` means start address plus byte count; `startAddress` + `endAddress` means inclusive bounds._", "");
+        }
         const toolPlatforms: readonly string[] = tool.metadata.platforms ?? ["c64u"];
         const opPlatformOverrides: Record<string, readonly string[]> = tool.metadata.operationPlatforms ?? {};
         const operationRows = operations
@@ -260,14 +388,15 @@ export function renderToolsSection(modules: readonly ToolModuleDescriptor[] = de
             return [
               `\`${operation.op}\``,
               escapeCell(operation.description),
-              escapeCell(toTableValue(operation.required.map((name) => `\`${name}\``))),
+              escapeCell(formatInputs(operation.required, operation.properties)),
+              escapeCell(formatInputs(operation.optional, operation.properties)),
               operation.notes.length ? escapeCell(operation.notes.join(", ")) : "—",
               effectivePlatforms.includes("c64u") ? "✅" : "",
               effectivePlatforms.includes("vice") ? "✅" : "",
             ];
           });
 
-        lines.push(renderTable(["Operation", "Description", "Required Inputs", "Notes", "C64U", "VICE"], operationRows));
+        lines.push(renderTable(["Operation", "Description", "Required Inputs", "Optional Inputs", "Notes", "C64U", "VICE"], operationRows));
       }
 
       lines.push("");

package/server.json

@@ -8,12 +8,12 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/chrisgleissner/c64bridge",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "c64bridge",
-      "version": "0.8.1",
+      "version": "0.9.1",
       "transport": {
         "type": "stdio"
       },