ggaction 0.0.7 → 0.0.9

package/src/mcp/adapter.js

@@ -0,0 +1,206 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { searchGgaction } from "../../knowledge/task-resolver.js";
+
+const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+const cardsArtifact = JSON.parse(readFileSync(
+  path.join(packageRoot, "knowledge/action-cards.json"),
+  "utf8"
+));
+const resourcesArtifact = JSON.parse(readFileSync(
+  path.join(packageRoot, "knowledge/mcp-resources.json"),
+  "utf8"
+));
+
+const cards = new Map(cardsArtifact.cards.map(card => [card.name, card]));
+const recipes = new Map(resourcesArtifact.recipes.map(recipe => [recipe.id, recipe]));
+const docs = new Map(resourcesArtifact.docs.map(section => [section.id, section]));
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+export const SEARCH_TOOL_NAME = "search_ggaction";
+export const OVERVIEW_URI = "ggaction://overview";
+
+export const SEARCH_TOOL = Object.freeze({
+  name: SEARCH_TOOL_NAME,
+  title: "Search ggaction authoring knowledge",
+  description: "Resolve one complete ggaction chart request into a bounded ordered task packet with exact imports, authoring prerequisites, executable immutable steps, terminal unsupported constraints, and explicit unresolved decisions.",
+  inputSchema: Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["query"],
+    properties: Object.freeze({
+      query: Object.freeze({
+        type: "string",
+        minLength: 1,
+        maxLength: 500,
+        description: "The exact user chart-authoring request, including chart, encodings, guides, layout, and output format. Do not append dataset contents, code scaffolding, or evaluator instructions."
+      })
+    })
+  }),
+  annotations: Object.freeze({
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  })
+});
+
+export class KnowledgeResourceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KnowledgeResourceError";
+  }
+}
+
+function jsonResource(uri, value) {
+  return Object.freeze({
+    uri,
+    mimeType: "application/json",
+    text: JSON.stringify(value)
+  });
+}
+
+function markdownResource(uri, value) {
+  return Object.freeze({
+    uri,
+    mimeType: "text/markdown",
+    text: `${value.text}\n\nCanonical public route: ${value.route}`
+  });
+}
+
+function encodedUri(owner, id) {
+  return `ggaction://${owner}/${encodeURIComponent(id)}`;
+}
+
+function parseResourceUri(uri) {
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    throw new KnowledgeResourceError(`Invalid knowledge resource URI: ${uri}`);
+  }
+  if (parsed.protocol !== "ggaction:" || parsed.search || parsed.hash) {
+    throw new KnowledgeResourceError(`Unsupported knowledge resource URI: ${uri}`);
+  }
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  return { owner: parsed.hostname, segments };
+}
+
+export function searchGgactionText(query) {
+  return JSON.stringify(searchGgaction(query));
+}
+
+export function docsFallbackResources(packet) {
+  if (!packet || !Array.isArray(packet.unresolved) || packet.unresolved.length === 0) {
+    return [];
+  }
+  for (const entry of packet.unresolved) {
+    if (!Array.isArray(entry.resources) || entry.resources.length === 0) {
+      throw new KnowledgeResourceError(
+        `Unresolved constraint ${entry.constraint ?? "unknown"} has no explicit documentation resource.`
+      );
+    }
+  }
+  const resources = unique(packet.unresolved.flatMap(entry => entry.resources));
+  return resources.map(uri => {
+    const { owner, segments } = parseResourceUri(uri);
+    if (owner !== "docs" || segments.length !== 1) {
+      throw new KnowledgeResourceError(`Invalid unresolved documentation resource: ${uri}`);
+    }
+    const id = decodeURIComponent(segments[0]);
+    const section = docs.get(id);
+    if (!section) {
+      throw new KnowledgeResourceError(`Unknown unresolved documentation resource: ${uri}`);
+    }
+    return Object.freeze({
+      uri,
+      name: section.title,
+      description: `Read only for the unresolved constraint; public route ${section.route}.`,
+      mimeType: "text/markdown"
+    });
+  });
+}
+
+export function listKnowledgeResources() {
+  return [
+    Object.freeze({
+      uri: OVERVIEW_URI,
+      name: resourcesArtifact.overview.title,
+      description: "Small MCP-first routing instructions; no complete documentation preload.",
+      mimeType: "application/json"
+    }),
+    ...resourcesArtifact.recipes.map(recipe => Object.freeze({
+      uri: encodedUri("recipes", recipe.id),
+      name: recipe.title,
+      description: recipe.summary,
+      mimeType: "application/json"
+    }))
+  ];
+}
+
+export function listKnowledgeResourceTemplates() {
+  return [
+    Object.freeze({
+      uriTemplate: "ggaction://actions/{name}",
+      name: "Exact compact action card",
+      description: "Read one exact action card by current public action name.",
+      mimeType: "application/json"
+    }),
+    Object.freeze({
+      uriTemplate: "ggaction://docs/{section}",
+      name: "Unresolved-only bounded documentation section",
+      description: "Read only a section recommended by the latest search_ggaction unresolved result.",
+      mimeType: "text/markdown"
+    })
+  ];
+}
+
+export function readKnowledgeResource(uri, { allowedDocs = [] } = {}) {
+  if (uri === OVERVIEW_URI) {
+    return jsonResource(uri, {
+      schemaVersion: resourcesArtifact.schemaVersion,
+      title: resourcesArtifact.overview.title,
+      text: resourcesArtifact.overview.text
+    });
+  }
+
+  const { owner, segments } = parseResourceUri(uri);
+  if (segments.length !== 1) {
+    throw new KnowledgeResourceError(`Unknown knowledge resource URI: ${uri}`);
+  }
+  const id = decodeURIComponent(segments[0]);
+  if (owner === "actions") {
+    const card = cards.get(id);
+    if (!card) throw new KnowledgeResourceError(`Unknown ggaction action: ${id}`);
+    return jsonResource(uri, card);
+  }
+  if (owner === "recipes") {
+    const recipe = recipes.get(id);
+    if (!recipe) throw new KnowledgeResourceError(`Unknown ggaction recipe: ${id}`);
+    return jsonResource(uri, {
+      schemaVersion: resourcesArtifact.schemaVersion,
+      ...recipe,
+      packet: searchGgaction(recipe.query)
+    });
+  }
+  if (owner === "docs") {
+    if (!new Set(allowedDocs).has(uri)) {
+      throw new KnowledgeResourceError(
+        "Documentation resources are available only when recommended by the latest unresolved search result."
+      );
+    }
+    const section = docs.get(id);
+    if (!section) throw new KnowledgeResourceError(`Unknown docs fallback section: ${id}`);
+    return markdownResource(uri, section);
+  }
+  throw new KnowledgeResourceError(`Unknown knowledge resource URI: ${uri}`);
+}
+
+if (cardsArtifact.schemaVersion !== 1 || resourcesArtifact.schemaVersion !== 2) {
+  throw new Error("MCP action cards must use schemaVersion 1 and resources schemaVersion 2.");
+}

package/src/mcp/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { runGgactionMcpServer } from "./server.js";
+
+try {
+  await runGgactionMcpServer();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`ggaction MCP failed: ${message}\n`);
+  process.exitCode = 1;
+}

package/src/mcp/server.js

@@ -0,0 +1,101 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+import {
+  docsFallbackResources,
+  KnowledgeResourceError,
+  listKnowledgeResources,
+  listKnowledgeResourceTemplates,
+  readKnowledgeResource,
+  SEARCH_TOOL,
+  SEARCH_TOOL_NAME,
+  searchGgactionText
+} from "./adapter.js";
+
+const SERVER_INFO = Object.freeze({ name: "ggaction", version: "1.0.0" });
+
+function toolError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true
+  };
+}
+
+function validateToolArguments(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    throw new TypeError("search_ggaction arguments must be an object with one query string.");
+  }
+  const names = Object.keys(args);
+  if (names.length !== 1 || names[0] !== "query") {
+    throw new TypeError("search_ggaction accepts exactly one argument: query.");
+  }
+  return args.query;
+}
+
+export function createGgactionMcpServer() {
+  const server = new Server(SERVER_INFO, {
+    capabilities: { tools: {}, resources: {} },
+    instructions: "Call search_ggaction once with only the exact user task; do not append dataset contents, code scaffolding, or evaluator instructions. Use authoring imports, initialization, prerequisites, and immutable steps in order. Treat unsupported entries as terminal limitations. Read only the resource URIs attached to unresolved entries. The server is read-only and does not execute chart code."
+  });
+  let allowedDocs = new Set();
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [SEARCH_TOOL]
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    if (request.params.name !== SEARCH_TOOL_NAME) {
+      throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+    }
+    try {
+      const query = validateToolArguments(request.params.arguments);
+      const text = searchGgactionText(query);
+      const packet = JSON.parse(text);
+      allowedDocs = new Set(docsFallbackResources(packet).map(resource => resource.uri));
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      allowedDocs = new Set();
+      return toolError(error);
+    }
+  });
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: listKnowledgeResources()
+  }));
+
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: listKnowledgeResourceTemplates()
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async request => {
+    try {
+      const resource = readKnowledgeResource(request.params.uri, {
+        allowedDocs: [...allowedDocs]
+      });
+      return { contents: [resource] };
+    } catch (error) {
+      if (error instanceof KnowledgeResourceError) {
+        throw new McpError(ErrorCode.InvalidParams, error.message);
+      }
+      throw error;
+    }
+  });
+
+  return server;
+}
+
+export async function runGgactionMcpServer() {
+  const server = createGgactionMcpServer();
+  await server.connect(new StdioServerTransport());
+  return server;
+}

package/types/index.d.ts

@@ -23,6 +23,9 @@ export type {
   Bin2DOutputFields,
   CanvasOptions,
   CategoricalEncodingOptions,
+  CategoryOrder,
+  CategoryOrderSummary,
+  CategoryValue,
   ColorLayout,
   ColorEncodingOptions,
   CompleteAxisOptions,
@@ -66,6 +69,7 @@ export type {
   DatasetFilterTransform,
   DatasetIntervalOutputFields,
   DatasetIntervalTransform,
+  DatasetTimeUnitTransform,
   DatasetWindowOperation,
   DatasetWindowSort,
   DatasetWindowTransform,
@@ -141,6 +145,7 @@ export type {
   ContinuousColorScaleOptions,
   OpacityEncodingOptions,
   OpacityScaleOptions,
+  OrderCategoriesOptions,
   OffsetScaleOptions,
   PathOrderEncodingOptions,
   ParallelCoordinatesEncodingOptions,
@@ -153,6 +158,7 @@ export type {
   Palette,
   PaletteName,
   PositionEncodingOptions,
+  YPositionEncodingOptions,
   RulePositionEncodingOptions,
   SecondaryPositionEncodingOptions,
   RegressionBandOptions,
@@ -165,6 +171,7 @@ export type {
   EditRegressionOptions,
   EditRectMarkOptions,
   RemoveAxisOptions,
+  RemoveCategoryOrderOptions,
   RemoveGridOptions,
   RemoveJitterOptions,
   RemoveLabelLayoutOptions,
@@ -175,6 +182,7 @@ export type {
   ScaleOptions,
   ScaleType,
   StackMode,
+  YStackMode,
   SemanticCoordinate,
   SemanticDataset,
   SemanticLayer,
@@ -186,6 +194,8 @@ export type {
   StrokeWidthScaleOptions,
   ThetaEncodingOptions,
   ThetaScaleOptions,
+  TimeUnit,
+  TimeUnitDataOptions,
   TraceNode,
   TitleOptions,
   EditTitleOptions,

package/types/program.d.ts

@@ -78,6 +78,7 @@ export type ScaleType =
   | "quantile"
   | "threshold";
 export type StackMode = "zero" | "normalize" | null;
+export type YStackMode = StackMode | "center";
 export type CompositionAlign = "start" | "center" | "end";
 export interface CompositionPadding {
   top?: number;
@@ -370,6 +371,15 @@ export type WindowOperation =
       as: string;
       offset?: number;
       default?: unknown;
+    }
+  | {
+      op: "movingMean" | "movingSum";
+      field: string;
+      as: string;
+      frame: {
+        preceding: number;
+        following?: number;
+      };
     };
 export interface DatasetWindowSort {
   readonly field: string;
@@ -388,6 +398,15 @@ export type DatasetWindowOperation =
       readonly as: string;
       readonly offset: number;
       readonly default: unknown;
+    }
+  | {
+      readonly op: "movingMean" | "movingSum";
+      readonly field: string;
+      readonly as: string;
+      readonly frame: {
+        readonly preceding: number;
+        readonly following: number;
+      };
     };
 export interface DatasetWindowTransform {
   readonly type: "window";
@@ -395,6 +414,20 @@ export interface DatasetWindowTransform {
   readonly sortBy: readonly DatasetWindowSort[];
   readonly operations: readonly DatasetWindowOperation[];
 }
+export type TimeUnit =
+  | "year"
+  | "quarter"
+  | "month"
+  | "day"
+  | "hour"
+  | "minute"
+  | "second";
+export interface DatasetTimeUnitTransform {
+  readonly type: "timeUnit";
+  readonly field: string;
+  readonly unit: TimeUnit;
+  readonly as: string;
+}
 export interface Bin2DCounts {
   x: number;
   y: number;
@@ -451,6 +484,7 @@ export type DatasetTransform =
   | DatasetDensityTransform
   | DatasetHorizonTransform
   | DatasetIntervalTransform
+  | DatasetTimeUnitTransform
   | DatasetWindowTransform;
 export interface CreateDerivedDataOptions {
   id: string;
@@ -518,7 +552,8 @@ export type ColorLayout =
   | "fill"
   | "group"
   | "overlay"
-  | "diverging";
+  | "diverging"
+  | "center";
 export type ScalarAggregateOperation =
   | "count" | "sum" | "mean" | "median" | "min" | "max"
   | "distinct" | "valid" | "missing"
@@ -918,6 +953,9 @@ export interface PositionEncodingOptions {
   stack?: StackMode;
 }
 
+export type YPositionEncodingOptions =
+  Omit<PositionEncodingOptions, "stack"> & { stack?: YStackMode };
+
 export interface ThetaScaleOptions {
   id?: string;
   type?: "linear" | "time" | "band" | "point";
@@ -1111,6 +1149,14 @@ export interface WindowDataOptions {
   operations: readonly WindowOperation[];
 }
 
+export interface TimeUnitDataOptions {
+  id: string;
+  source?: string;
+  field: string;
+  unit: TimeUnit;
+  as: string;
+}
+
 export interface Bin2DDataOptions {
   id: string;
   source?: string;
@@ -2098,6 +2144,31 @@ export interface RemovePathOrderOptions {
   target?: string;
 }
 
+export type CategoryValue = string | number | boolean;
+export type CategoryOrderSummary = {
+  field: string;
+  aggregate: "sum" | "mean" | "min" | "max";
+};
+export type CategoryOrder =
+  | {
+      values: readonly CategoryValue[];
+      by?: never;
+      direction?: never;
+    }
+  | {
+      values?: never;
+      by: "category" | "count" | CategoryOrderSummary;
+      direction?: "ascending" | "descending";
+    };
+export type OrderCategoriesOptions = {
+  target?: string;
+  channel: "x" | "y";
+} & CategoryOrder;
+export interface RemoveCategoryOrderOptions {
+  target?: string;
+  channel: "x" | "y";
+}
+
 export interface TitleOptions {
   text: string;
   subtitle?: string;
@@ -2143,6 +2214,7 @@ export class ChartProgram {
   createDensityData(options: DensityDataOptions): ChartProgram;
   createRegressionData(options: RegressionDataOptions): ChartProgram;
   createIntervalData(options: IntervalDataOptions): ChartProgram;
+  createTimeUnitData(options: TimeUnitDataOptions): ChartProgram;
   createWindowData(options: WindowDataOptions): ChartProgram;
   createBin2DData(options: Bin2DDataOptions): ChartProgram;
   editBin2DData(options: EditBin2DDataOptions): ChartProgram;
@@ -2164,6 +2236,21 @@ export class ChartProgram {
     stroke?: string | false;
     strokeWidth?: number;
   }): ChartProgram;
+  createTickMark(options?: {
+    id?: string;
+    data?: string;
+    length?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+  }): ChartProgram;
+  editTickMark(options: {
+    target?: string;
+    length?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+  }): ChartProgram;
   jitterPoints(options: JitterPointsOptions): ChartProgram;
   removeJitter(options?: RemoveJitterOptions): ChartProgram;
   createLineMark(options?: {
@@ -2243,7 +2330,7 @@ export class ChartProgram {
   }): ChartProgram;
 
   encodeX(options: PositionEncodingOptions | RulePositionEncodingOptions): ChartProgram;
-  encodeY(options: PositionEncodingOptions | RulePositionEncodingOptions): ChartProgram;
+  encodeY(options: YPositionEncodingOptions | RulePositionEncodingOptions): ChartProgram;
   encodeTheta(options: ThetaEncodingOptions): ChartProgram;
   encodeR(options: RadialEncodingOptions): ChartProgram;
   encodeX2(options: SecondaryPositionEncodingOptions): ChartProgram;
@@ -2251,6 +2338,10 @@ export class ChartProgram {
   encodeStrokeDash(options: StrokeDashEncodingOptions): ChartProgram;
   encodeSize(options: { field: string; target?: string; fieldType?: "quantitative"; scale?: ScaleOptions }): ChartProgram;
   encodeShape(options: { field: string; target?: string; fieldType?: "nominal"; scale?: ScaleOptions }): ChartProgram;
+  encodeAngle(options:
+    | { target?: string; value: number; field?: never; fieldType?: never }
+    | { target?: string; field: string; fieldType?: "quantitative"; value?: never }
+  ): ChartProgram;
   encodeOpacity(options: OpacityEncodingOptions): ChartProgram;
   encodeRadius(options: { value: number; target?: string }): ChartProgram;
   encodePointRadius(options: { value: number; target?: string }): ChartProgram;
@@ -2276,14 +2367,16 @@ export class ChartProgram {
   }): ChartProgram;
   encodeGroup(options: { field: string; target?: string; fieldType?: "nominal" }): ChartProgram;
   encodePathOrder(options: PathOrderEncodingOptions): ChartProgram;
+  orderCategories(options: OrderCategoriesOptions): ChartProgram;
   encodeParallelCoordinates(options: ParallelCoordinatesEncodingOptions): ChartProgram;
   removePathOrder(options?: RemovePathOrderOptions): ChartProgram;
+  removeCategoryOrder(options: RemoveCategoryOrderOptions): ChartProgram;
   removeEncoding(options: {
     target?: string;
     channel:
       | "x" | "y" | "x2" | "y2" | "xOffset" | "yOffset"
       | "theta" | "radius" | "color" | "strokeDash" | "strokeWidth"
-      | "size" | "shape" | "group" | "opacity" | "text";
+      | "size" | "shape" | "angle" | "group" | "opacity" | "text";
   }): ChartProgram;
   encodeText(options: TextEncodingOptions): ChartProgram;
   encodeHistogram(options: HistogramEncodingOptions): ChartProgram;

package/src/actions/coordinates/index.js

@@ -1,5 +0,0 @@
-import { createCoordinate } from "./actions.js";
-
-export function registerCoordinateActions(ProgramClass) {
-  ProgramClass.prototype.createCoordinate = createCoordinate;
-}

package/src/actions/primitives/semanticValue.js

@@ -1 +0,0 @@
-export { validateSemanticValue } from "./semanticValidation/index.js";