@elaraai/e3-cloud-claude-plugin 1.0.97 → 1.1.1

package/.build/hooks/pre-read.js

@@ -1,4 +1,4 @@
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 var isCodex = existsSync(fileURLToPath(new URL("../../.codex-plugin/plugin.json", import.meta.url)));
@@ -6,7 +6,7 @@ function hostText(text) {
   return isCodex ? text.replaceAll("mcp__plugin_east_east__", "").replaceAll("/east:", "$east-codex-plugin:").replaceAll("Claude Code", "Codex") : text;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
 async function readHookInput() {
   let input = "";
   for await (const chunk of process.stdin) {
@@ -34,10 +34,10 @@ function writeHookDecision(hookEventName, decision, reason) {
   process.stdout.write(JSON.stringify(output));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -79,7 +79,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 function preReadReminder(event, options) {
   return options.isCorpusRead(event.tool_name ?? "", event.tool_input ?? {}) ? { decision: "context", text: options.readText } : null;
 }

package/.build/hooks/pre-write.js

@@ -1,10 +1,10 @@
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 import { readFile as readFile2 } from "node:fs/promises";
 import { existsSync as existsSync2, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/host.js
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 var isCodex = existsSync(fileURLToPath(new URL("../../.codex-plugin/plugin.json", import.meta.url)));
@@ -12,7 +12,7 @@ function hostText(text) {
   return isCodex ? text.replaceAll("mcp__plugin_east_east__", "").replaceAll("/east:", "$east-codex-plugin:").replaceAll("Claude Code", "Codex") : text;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/hook-io.js
 async function readHookInput() {
   let input = "";
   for await (const chunk of process.stdin) {
@@ -40,7 +40,7 @@ function writeHookDecision(hookEventName, decision, reason) {
   process.stdout.write(JSON.stringify(output));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 import { readFile } from "node:fs/promises";
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 async function searchedInTranscript(transcriptPath, tools = SEARCH_TOOLS) {
@@ -53,7 +53,7 @@ async function searchedInTranscript(transcriptPath, tools = SEARCH_TOOLS) {
   return tools.some((tool) => raw.includes(`"name":"${tool}"`) || raw.includes(`"name": "${tool}"`));
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -95,7 +95,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-hooks.js
 async function preWriteGate(event, options) {
   const cwd = event.cwd || process.cwd();
   const filePath = event.tool_input?.file_path;

package/.build/mcp/server.js

@@ -15140,7 +15140,7 @@ function object(shape, params) {
   return new ZodMiniObject(def);
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
 function isZ4Schema(s) {
   const schema = s;
   return !!schema._zod;
@@ -15995,7 +15995,7 @@ function preprocess(fn, schema) {
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v4/classic/external.js
 config(en_default2());
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
 var LATEST_PROTOCOL_VERSION = "2025-11-25";
 var SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"];
 var RELATED_TASK_META_KEY = "io.modelcontextprotocol/related-task";
@@ -17526,7 +17526,7 @@ var UrlElicitationRequiredError = class extends McpError {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.js
 function isTerminal(status) {
   return status === "completed" || status === "failed" || status === "cancelled";
 }
@@ -18815,7 +18815,7 @@ var zodToJsonSchema = (schema, options) => {
   return combined;
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-json-schema-compat.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-json-schema-compat.js
 function mapMiniTarget(t) {
   if (!t)
     return "draft-7";
@@ -18857,7 +18857,7 @@ function parseWithCompat(schema, data) {
   return result.data;
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js
 var DEFAULT_REQUEST_TIMEOUT_MSEC = 6e4;
 var Protocol = class {
   constructor(_options) {
@@ -19834,7 +19834,7 @@ function mergeCapabilities(base, additional) {
   return result;
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/validation/ajv-provider.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/validation/ajv-provider.js
 var import_ajv = __toESM(require_ajv(), 1);
 var import_ajv_formats = __toESM(require_dist(), 1);
 function createDefaultAjvInstance() {
@@ -19902,7 +19902,7 @@ var AjvJsonSchemaValidator = class {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/server.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/server.js
 var ExperimentalServerTasks = class {
   constructor(_server) {
     this._server = _server;
@@ -20115,7 +20115,7 @@ var ExperimentalServerTasks = class {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
 function assertToolsCallTaskCapability(requests, method, entityName) {
   if (!requests) {
     throw new Error(`${entityName} does not support task creation (required for ${method})`);
@@ -20150,7 +20150,7 @@ function assertClientRequestTaskCapability(requests, method, entityName) {
   }
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
 var Server = class extends Protocol {
   /**
    * Initializes this server with the given name and version information.
@@ -20521,7 +20521,7 @@ var Server = class extends Protocol {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
 var COMPLETABLE_SYMBOL = /* @__PURE__ */ Symbol.for("mcp.completable");
 function isCompletable(schema) {
   return !!schema && typeof schema === "object" && COMPLETABLE_SYMBOL in schema;
@@ -20535,7 +20535,7 @@ var McpZodTypeKind;
   McpZodTypeKind2["Completable"] = "McpCompletable";
 })(McpZodTypeKind || (McpZodTypeKind = {}));
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/toolNameValidation.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/toolNameValidation.js
 var TOOL_NAME_REGEX = /^[A-Za-z0-9._-]{1,128}$/;
 function validateToolName(name) {
   const warnings = [];
@@ -20593,7 +20593,7 @@ function validateAndWarnToolName(name) {
   return result.isValid;
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/mcp-server.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/mcp-server.js
 var ExperimentalMcpServerTasks = class {
   constructor(_mcpServer) {
     this._mcpServer = _mcpServer;
@@ -20608,7 +20608,7 @@ var ExperimentalMcpServerTasks = class {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
 function toolInputElementCount(value, max) {
   let count = 0;
   const stack = [value];
@@ -20657,6 +20657,15 @@ var McpServer = class {
     this._promptHandlersInitialized = false;
     this.server = new Server(serverInfo, options);
     this._maxToolInputElements = resolveMaxToolInputElements(options?.maxToolInputElements);
+    if (options?.capabilities?.tools) {
+      this.setToolRequestHandlers();
+    }
+    if (options?.capabilities?.resources) {
+      this.setResourceRequestHandlers();
+    }
+    if (options?.capabilities?.prompts) {
+      this.setPromptRequestHandlers();
+    }
   }
   /**
    * Access experimental features.
@@ -21440,10 +21449,10 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 import process from "node:process";
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
 var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
   constructor(options) {
@@ -21480,7 +21489,7 @@ function serializeMessage(message) {
   return JSON.stringify(message) + "\n";
 }
 
-// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.1_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
+// ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.32.2_zod@3.25.76/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
   constructor(_stdin = process.stdin, _stdout = process.stdout, options) {
     this._stdin = _stdin;
@@ -21547,7 +21556,7 @@ var StdioServerTransport = class {
   }
 };
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 import { readFile } from "node:fs/promises";
 
 // ../../node_modules/.pnpm/minisearch@7.2.0/node_modules/minisearch/dist/es/index.js
@@ -23360,7 +23369,7 @@ var objectToNumericMapAsync = async (object3) => {
 var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var SPACE_OR_PUNCTUATION = /[\n\r\p{Z}\p{P}]+/u;
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search-guidance.js
 var EAST_GUIDANCE = {
   searchTool: "mcp__plugin_east_east__search_east_examples",
   getTool: "mcp__plugin_east_east__get_east_example",
@@ -23402,7 +23411,7 @@ var GATE_TEXT = gateText(EAST_GUIDANCE);
 var READ_TEXT = readText(EAST_GUIDANCE);
 var isExampleCorpusRead = corpusReadFor(EAST_GUIDANCE.scope);
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/search.js
 var MIN_SCORE = 5;
 async function loadIndexes(indexPaths) {
   const entries = [];
@@ -23444,6 +23453,7 @@ function normalizePackage(filter, scopes = EAST_SCOPES) {
   const scope = scopes.find((s) => name.startsWith(`${s.toLowerCase()}/`));
   return scope === void 0 ? name : name.slice(scope.length + 1);
 }
+var OPT_IN_PACKAGES = /* @__PURE__ */ new Set(["east-values"]);
 function searchExamples(index, request) {
   const known = index.packages;
   const filter = request.package;
@@ -23453,7 +23463,7 @@ function searchExamples(index, request) {
   }
   const options = {
     limit: request.limit,
-    ...pkg === void 0 ? {} : { filter: (r) => r.package === pkg || r.skill === pkg }
+    filter: (r) => OPT_IN_PACKAGES.has(r.package) ? r.package === pkg : pkg === void 0 || r.package === pkg || r.skill === pkg
   };
   const hits = index.search.search(request.query, options);
   return { entries: hits.filter((r) => r.score >= MIN_SCORE).slice(0, request.limit), known };
@@ -23527,7 +23537,7 @@ function getEntry(index, id) {
   return stored === void 0 ? null : stored;
 }
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/mcp/example-tools.js
 var EAST_PACKAGES = ["east", "east-node-std", "east-node-io", "east-py-datascience", "east-ui", "e3-ui", "e3", "e3-ui-cli", "e3-create"];
 function isLoaded(index) {
   return typeof index.then === "function";
@@ -23548,7 +23558,7 @@ function registerExampleTools(server2, options) {
     language: languageArg,
     format: external_exports.enum(["summary", "full"]).default("summary").describe(`"summary" (default) lists the hits in one line each; "full" includes each hit's code in the requested language`),
     limit: external_exports.number().int().min(1).max(20).default(5).describe("Maximum number of results to return (default 5, max 20)"),
-    package: external_exports.string().optional().describe(`Filter results to one package by its bare name \u2014 ${packages.join(", ")} \u2014 ${scopesNamed}; an unknown name is reported with the indexed names`)
+    package: external_exports.string().optional().describe(`Filter results to one package by its bare name \u2014 ${packages.join(", ")} \u2014 ${scopesNamed}; an unknown name is reported with the indexed names${packages.includes("east-values") ? '. "east-values" is east-py code working with East values directly (eager methods on python values, not an East function), and is searched only when named here' : ""}`)
   }, async ({ query, language, format, limit, package: packageFilter }) => {
     const index = await indexPromise;
     const { entries, unknownPackage, known } = searchExamples(index, { query, limit, package: packageFilter, scopes });
@@ -23600,7 +23610,7 @@ function registerExampleTools(server2, options) {
 import { fileURLToPath } from "node:url";
 var E3_CLOUD_INDEX_PATH = fileURLToPath(new URL("../../index.json", import.meta.url));
 
-// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.97_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
+// ../../node_modules/.pnpm/@elaraai+east-plugin@1.0.101_typescript@5.9.3/node_modules/@elaraai/east-plugin/dist/lib/transcript.js
 var SEARCH_TOOLS = ["mcp__plugin_east_east__search_east_examples", "mcp__plugin_east_east__get_east_example", "mcp__east__search_east_examples", "mcp__east__get_east_example"];
 
 // ../e3-cloud-plugin/dist/lib/names.js

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "e3-cloud",
-  "version": "1.0.97",
+  "version": "1.1.1",
   "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
   "author": {
     "name": "Elara AI",

package/README.md

@@ -66,8 +66,9 @@ reminded that the index is the same code, cheaper.
 
 ## Version
 
-The @elaraai lockstep, as every e3 cloud package's: the release of e3 cloud's
-packages is the release of this plugin.
+e3 cloud's version, as every e3 cloud package's: the release of e3 cloud's
+packages is the release of this plugin, and documents the packages of its
+version.
 
 ## Developing it
 

package/index.json

@@ -1,13 +1,13 @@
 {
   "version": 2,
   "stats": {
-    "totalEntries": 40,
+    "totalEntries": 47,
     "totalFiles": 2,
     "packages": {
       "e3-cloud-ui": 12,
-      "e3-cloud-files": 11,
-      "e3-cloud-cli": 13,
-      "e3-cloud-client": 4
+      "e3-cloud-files": 14,
+      "e3-cloud-cli": 15,
+      "e3-cloud-client": 6
     }
   },
   "entries": [
@@ -183,7 +183,7 @@
       "package": "e3-cloud-ui",
       "file": "packages/e3-cloud-ui/test/pages.examples.tsx",
       "suite": "Functions and records",
-      "test": "Changing a record from a page: Record.bind(orders, [approve]) names the mutations the page may run, and o.mutate.approve(id) commits one",
+      "test": "Changing a record from a page: Record.bind(orders, ['approve']) names the mutations the page may run, by the names the record declares them under, and o.mutate.approve(id) commits one",
       "keywords": [
         "Record.bind",
         "mutate",
@@ -203,7 +203,7 @@
       "languages": [
         "tsx"
       ],
-      "source": "// Changing a record from a page: Record.bind(orders, [approve]) names the mutations the page may run, and o.mutate.approve(id) commits one\n// inputs: []\n/** The runtime the package's functions run on. */\nconst RUNNER: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations. */\nconst orders = e3.record('orders', DictType(StringType, Order), new Map());\n\n/** Approves an order by its id. */\nconst approve = e3.mutation.reduce('approve', orders,\n  East.function([DictType(StringType, Order), StringType], DictType(StringType, Order), (_$, all, _id) => all),\n  { runner: RUNNER });\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const o = $.let(Record.bind(orders, [approve]));\n      const approveA17 = $.const(East.function([], NullType, $ => { $(o.mutate.approve('A-17')); }));\n      return <Button onClick={approveA17}>Approve A-17</Button>;\n    }}</Reactive>\n  ))"
+      "source": "// Changing a record from a page: Record.bind(orders, ['approve']) names the mutations the page may run, by the names the record declares them under, and o.mutate.approve(id) commits one\n// inputs: []\n/** The runtime the package's functions run on. */\nconst RUNNER: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations, declared whole with its index and its mutation. */\nconst orders = e3.record('orders', DictType(StringType, Order), {\n  initial: new Map(),\n  indexes: (index) => ({\n    /** The orders by line. */\n    by_line: index.key(East.function([StringType, Order], StringType, (_$, _id, o) => o.line)),\n  }),\n  mutations: (mutation) => ({\n    /** Approves an order by its id. */\n    approve: mutation.reduce(\n      East.function([DictType(StringType, Order), StringType], DictType(StringType, Order), (_$, all, _id) => all),\n      { runner: RUNNER }),\n  }),\n});\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const o = $.let(Record.bind(orders, ['approve']));\n      const approveA17 = $.const(East.function([], NullType, $ => { $(o.mutate.approve('A-17')); }));\n      return <Button onClick={approveA17}>Approve A-17</Button>;\n    }}</Reactive>\n  ))"
     },
     {
       "id": "e3-cloud-ui:pages.examples.tsx:pageReadsARecordThroughAnIndex",
@@ -211,11 +211,11 @@
       "package": "e3-cloud-ui",
       "file": "packages/e3-cloud-ui/test/pages.examples.tsx",
       "suite": "Functions and records",
-      "test": "Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: byLine }) given the index's declaration, its rows the index key and the order's id",
+      "test": "Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: 'by_line' }) given the name the record declares the index under, its rows the index key and the order's id",
       "keywords": [
         "Data.bindPaged",
         "index",
-        "recordIndex",
+        "indexes",
         "record",
         "paged",
         "Table",
@@ -232,7 +232,7 @@
       "languages": [
         "tsx"
       ],
-      "source": "// Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: byLine }) given the index's declaration, its rows the index key and the order's id\n// inputs: []\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations. */\nconst orders = e3.record('orders', DictType(StringType, Order), new Map());\n\n/** The orders by line. */\nconst byLine = e3.recordIndex('by_line', orders,\n  { key: East.function([StringType, Order], StringType, (_$, _id, o) => o.line) });\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const mine = $.let(Data.bindPaged(orders, { index: byLine }));\n      return <Table data={mine} columns={['ik', 'key']} />;\n    }}</Reactive>\n  ))"
+      "source": "// Reading a record through one of its indexes, a page at a time: Data.bindPaged(orders, { index: 'by_line' }) given the name the record declares the index under, its rows the index key and the order's id\n// inputs: []\n/** The runtime the package's functions run on. */\nconst RUNNER: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n\nconst Order = StructType({ line: StringType, qty: FloatType, status: StringType });\n\n/** A record of orders, changed only through its mutations, declared whole with its index and its mutation. */\nconst orders = e3.record('orders', DictType(StringType, Order), {\n  initial: new Map(),\n  indexes: (index) => ({\n    /** The orders by line. */\n    by_line: index.key(East.function([StringType, Order], StringType, (_$, _id, o) => o.line)),\n  }),\n  mutations: (mutation) => ({\n    /** Approves an order by its id. */\n    approve: mutation.reduce(\n      East.function([DictType(StringType, Order), StringType], DictType(StringType, Order), (_$, all, _id) => all),\n      { runner: RUNNER }),\n  }),\n});\n\nEast.function([], UIComponentType, _$ => (\n    <Reactive>{$ => {\n      const mine = $.let(Data.bindPaged(orders, { index: 'by_line' }));\n      return <Table data={mine} columns={['ik', 'key']} />;\n    }}</Reactive>\n  ))"
     },
     {
       "id": "e3-cloud-files:decode.examples.ts:fileAsJson",
@@ -314,6 +314,34 @@
       ],
       "source": "// A text file input's lines, trimmed, blank ones left out\n// inputs: [utf8('first\\n\\n  second  \\nthird\\n')]  returns: ['first', 'second', 'third']\nEast.function([BlobType], ArrayType(StringType), (_$, file) =>\n    file.decodeUtf8().split('\\n').map((_$, line) => line.trim()).filter((_$, line) => line.notEquals('')))"
     },
+    {
+      "id": "e3-cloud-files:decode.examples.ts:typedFileAsItsValue",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "packages/e3-cloud-files/test/decode.examples.ts",
+      "suite": "A typed file: no decoding",
+      "test": "A typed input needs no decoding: what upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) }) fills is the beast2 file's value itself, an Array<Price> the task takes as any dataset, here counted",
+      "keywords": [
+        "Files",
+        "typed",
+        "type",
+        "beast2",
+        "file",
+        "latest",
+        "no decoding",
+        "ArrayType",
+        "size",
+        "task"
+      ],
+      "imports": [
+        "import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';",
+        "import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';"
+      ],
+      "languages": [
+        "typescript"
+      ],
+      "source": "// A typed input needs no decoding: what upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) }) fills is the beast2 file's value itself, an Array<Price> the task takes as any dataset, here counted\n// inputs: [[{ sku: 'A1', price: 1.5 }, { sku: 'B2', price: 2.25 }, { sku: 'C3', price: 9 }]]  returns: 3n\nconst Price = StructType({ sku: StringType, price: FloatType });\n\nEast.function([ArrayType(Price)], IntegerType, (_$, prices) => prices.size())"
+    },
     {
       "id": "e3-cloud-files:decode.examples.ts:folderAsOneArray",
       "skill": "e3-cloud-files",
@@ -593,35 +621,104 @@
       ]
     },
     {
-      "id": "e3-cloud-files:static:typed",
+      "id": "e3-cloud-files:static:typed-input",
       "skill": "e3-cloud-files",
       "package": "e3-cloud-files",
       "file": "static",
       "suite": "Files",
-      "test": "A beast2 file as an input of its type with no task in between (file or latest with a type), and a record's mutation fed by each new file: the declarations, the package, and what a sync does with them",
+      "test": "A beast2 file as an input of its type with no task in between: file or latest with a type, a collection of any size, its header checked before any other byte, a file of another type refused naming both types, the same bytes under a new ETag changing nothing",
       "keywords": [
         "Files",
         "type",
         "beast2",
         "typed",
+        "typed input",
         "ArrayType",
         "upload.file",
         "upload.latest",
-        "upload.mutation",
-        "mutation",
-        "feed",
-        "record",
-        "e3.mutation.reduce",
         "encodeBeast2For",
+        "Beast2ElementWriter",
         "collection",
+        "type_mismatch",
+        "not_beast2",
         "e3-cloud-files"
       ],
       "imports": [
-        "import { East, ArrayType, DictType, FloatType, IntegerType, StringType, StructType } from '@elaraai/east';",
+        "import { East, ArrayType, FloatType, IntegerType, StringType, StructType } from '@elaraai/east';",
         "import e3, { type Runner } from '@elaraai/e3';",
         "import { Files } from '@elaraai/e3-cloud-files';"
       ],
-      "source": "// src/package.ts\nconst Price = StructType({ sku: StringType, price: FloatType });\nconst PriceBook = DictType(StringType, FloatType);\nexport const upload = Files.source('upload');\n// A beast2 file of Array<Price> (encodeBeast2For(ArrayType(Price)), east-py, e3 convert): an input of that type, taken in as the\n// value it holds, a collection of any size, its header checked first; a file of another type is refused naming both types\nexport const prices = upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) });\nexport const stock = upload.latest('stock', { prefix: 'stock/', include: '*.beast2', type: ArrayType(Price) });   // the greatest key, typed\n// A record the app's users edit, and a mutation of one argument that loads a delivery into it\nexport const priceBook = e3.record('price_book', PriceBook, new Map());\nexport const loadPrices = e3.mutation.reduce('load_prices', priceBook, East.function([PriceBook, ArrayType(Price)], PriceBook, ($, state, rows) => {\n  const next = $.let(state.copy());   // the book as it is (a mutation's state is immutable), each delivered price over its sku's\n  $.for(rows, ($, row) => { $(next.insertOrUpdate(row.sku, row.price, (_$, _existing, delivered) => delivered)); });\n  return next;\n}));\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\nexport const summary = e3.task('price_summary', [prices, priceBook], East.function([ArrayType(Price), PriceBook], IntegerType, (_$, rows, book) => rows.size().add(book.size())), { runner });\nexport default e3.package('typed', '1.0.0', summary, loadPrices);\n\n// src/files.ts: each new delta file under deltas/ calls load_prices once with its value, by the file's hash; a refused file is\n// tried again only once it changes; a feed of a record with no state yet waits for it\nupload.mutation(loadPrices, { prefix: 'deltas/', include: '*.beast2' });\nexport default Files.manifest([upload]);",
+      "source": "// src/package.ts\nconst Price = StructType({ sku: StringType, price: FloatType });\nexport const upload = Files.source('upload');\n// A beast2 file of Array<Price> (encodeBeast2For(ArrayType(Price)), a Beast2ElementWriter for a collection of any size, east-py, e3 convert):\n// an input of that type, taken in as the value it holds, its header checked before any other byte is read; a file of another type is\n// refused naming both types (type_mismatch), no beast2 at all as not_beast2, and the input keeps its value. The same bytes again under\n// a new ETag give the same value: nothing downstream runs\nexport const prices = upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) });\nexport const stock = upload.latest('stock', { prefix: 'stock/', include: '*.beast2', type: ArrayType(Price) });   // the greatest key, typed\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\n// Used as any dataset: no decoding, the value is the file's\nexport const summary = e3.task('price_summary', [prices, stock], East.function([ArrayType(Price), ArrayType(Price)], IntegerType, (_$, rows, latest) => rows.size().add(latest.size())), { runner });\nexport default e3.package('typed', '1.0.0', summary);\n\n// src/files.ts\nexport default Files.manifest([upload]);",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-files:static:record-seed",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "static",
+      "suite": "Files",
+      "test": "A record seeded from a file: upload.record(name, type, spec, parts) is e3.record(name, type, parts) with no initial value, declared whole with its indexes, mutations and migrations, pending until its file arrives (its first state, $init), seeded again by a changed file while nothing has mutated it since ($seed) or on --reset, kept once mutated; the tasks over it wait meanwhile, and its history names the file",
+      "keywords": [
+        "Files",
+        "record",
+        "seed",
+        "seeded",
+        "upload.record",
+        "pending",
+        "$init",
+        "$seed",
+        "--reset",
+        "genesis",
+        "no initial value",
+        "e3.record",
+        "declared whole",
+        "mutations",
+        "kept",
+        "waiting",
+        "e3-cloud-files"
+      ],
+      "imports": [
+        "import { East, DictType, IntegerType, StringType, StructType } from '@elaraai/east';",
+        "import e3, { type Runner } from '@elaraai/e3';",
+        "import { Files } from '@elaraai/e3-cloud-files';"
+      ],
+      "source": "// src/package.ts\nconst Customer = StructType({ name: StringType, tier: IntegerType });\nconst CustomerBook = DictType(StringType, Customer);\nexport const upload = Files.source('upload');\n// e3.record('customers', CustomerBook, parts) with no initial value: pending until customers.beast2 arrives, which is its first state ($init:\n// nothing runs on an empty state first, and the tasks over it wait as on an unset input, the run completing without them); a changed\n// file while nothing has mutated it since is its state again ($seed); once mutated it is kept, until `files sync --reset customers`\n// (or `files push --reset customers`) takes the file as its state over whatever was done. The workspace page shows it Pending, its page\n// what seeds it, `files status` prints pending; its history reads \"Initialised from customers.beast2 (2 rows)\" and \"Seeded again from …\"\n// Declared whole, as any record is: its indexes, mutations and migrations are the fourth argument, as e3.record takes them (an initial\n// value there is refused). Its mutations are any record's: after one, the file no longer seeds it until a reset\nexport const customers = upload.record('customers', CustomerBook, { key: 'customers.beast2' }, {\n  mutations: (mutation) => ({\n    set_tier: mutation.reduce(East.function([CustomerBook, StringType, IntegerType], CustomerBook, ($, state, key, tier) => {\n      const next = $.let(state.copy());\n      $(next.insertOrUpdate(key, { name: key, tier }, (_$, existing, _given) => ({ name: existing.name, tier })));\n      return next;\n    })),\n  }),\n});\nconst runner: Runner = { runtime: 'east-c', platforms: ['east-c-std'] };\nexport const customerCount = e3.task('customer_count', [customers], East.function([CustomerBook], IntegerType, (_$, book) => book.size()), { runner });\n// The record carries its mutation: the package takes the task over it\nexport default e3.package('typed', '1.0.0', customerCount);\n\n// src/files.ts\nexport default Files.manifest([upload]);\n\n// A deploy that cannot keep the record (its type changed) under --schema reset unassigns it: pending again, seeded by the next\n// version's file once the new declarations are deployed",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-files:static:mutation-feed",
+      "skill": "e3-cloud-files",
+      "package": "e3-cloud-files",
+      "file": "static",
+      "suite": "Files",
+      "test": "A record's mutation fed by files: upload.mutation(def, spec), def one the record declares (priceBook.mutations.load_prices), applies each new file the spec selects, in key order, once by its bytes' hash, as the mutation's one argument; a refused file is tried again only once it changes, a feed of a pending record waits, and each commit names its file",
+      "keywords": [
+        "Files",
+        "mutation",
+        "feed",
+        "fed",
+        "upload.mutation",
+        "mutation.reduce",
+        "mutations",
+        "one argument",
+        "idempotent",
+        "once per file",
+        "key order",
+        "refused",
+        "waiting",
+        "deltas",
+        "e3-cloud-files"
+      ],
+      "imports": [
+        "import { East, ArrayType, DictType, FloatType, StringType, StructType } from '@elaraai/east';",
+        "import e3 from '@elaraai/e3';",
+        "import { Files } from '@elaraai/e3-cloud-files';"
+      ],
+      "source": "// src/package.ts\nconst Price = StructType({ sku: StringType, price: FloatType });\nconst PriceBook = DictType(StringType, FloatType);\nexport const upload = Files.source('upload');\n// A record the app's users edit, declared whole with a mutation of one argument that loads a delivery into it: the record's own\n// reduce (or edit; a patch cannot be fed), its rules deciding what a delivery does. A delivery holding a price below zero is refused\n// whole: the mutation fails, the book is kept, and the file is tried again only once it changes, the files after it waiting\nexport const priceBook = e3.record('price_book', PriceBook, {\n  initial: new Map(),\n  mutations: (mutation) => ({\n    load_prices: mutation.reduce(East.function([PriceBook, ArrayType(Price)], PriceBook, ($, state, rows) => {\n      const next = $.let(state.copy());   // the book as it is (a mutation's state is immutable), each delivered price over its sku's\n      $.for(rows, ($, row) => {\n        $.if(row.price.lessThan(0), ($) => $.error(East.str`a price below zero: ${row.sku}`));\n        $(next.insertOrUpdate(row.sku, row.price, (_$, _existing, delivered) => delivered));\n      });\n      return next;\n    })),\n  }),\n});\n// The record carries its mutation: the package takes the record\nexport default e3.package('typed', '1.0.0', priceBook);\n\n// src/files.ts: each new delta file under deltas/ calls load_prices once with its value, by the file's hash (a sync run again\n// applies nothing twice; the same bytes under another name are applied no more); a feed of a record with no state yet waits for\n// it; a sync seeds records before it feeds mutations. The commit reads in the record's history as any mutation's, through the\n// files channel, naming the file it was fed\nupload.mutation(priceBook.mutations.load_prices, { prefix: 'deltas/', include: '*.beast2' });\nexport default Files.manifest([upload]);",
       "languages": [
         "typescript"
       ]
@@ -661,7 +758,7 @@
       "package": "e3-cloud-cli",
       "file": "static",
       "suite": "e3-cloud",
-      "test": "Signing in to a deployment, and who you are there: the e3 CLI's sign-in (`e3 auth login`; there is no `e3 login`), whose credentials the e3-cloud CLI shares",
+      "test": "Signing in to a deployment, and who you are there: the e3 CLI's sign-in (`e3 auth login`; there is no `e3 login`), whose credentials the e3-cloud CLI shares; whoami names the e3 cloud release and e3 the deployment runs beside this CLI's",
       "keywords": [
         "login",
         "sign in",
@@ -674,7 +771,36 @@
         "e3-cloud"
       ],
       "imports": [],
-      "source": "npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli\ne3 auth login https://e3.example.com     # the device flow; e3-cloud reads the same credentials\ne3-cloud whoami https://e3.example.com   # your identity there, and whether you are an admin",
+      "source": "npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli\ne3 auth login https://e3.example.com     # the device flow; e3-cloud reads the same credentials\ne3-cloud whoami https://e3.example.com   # your identity there, whether you are an admin, and the releases (e3-cloud --version, below)",
+      "languages": [
+        "typescript"
+      ]
+    },
+    {
+      "id": "e3-cloud-cli:static:versions",
+      "skill": "e3-cloud-cli",
+      "package": "e3-cloud-cli",
+      "file": "static",
+      "suite": "e3-cloud --version / whoami",
+      "test": "Which releases a push or a deploy depends on: this CLI's e3 cloud release and the east and e3 it is built with (--version, --json), and the deployment's release and e3 (whoami), with a note where their e3s differ: a package exported with a newer e3 than the deployment's is refused",
+      "keywords": [
+        "version",
+        "--version",
+        "-V",
+        "--json",
+        "whoami",
+        "release",
+        "e3 version",
+        "east version",
+        "deployment",
+        "platform",
+        "lockstep",
+        "compatible",
+        "staged for",
+        "e3-cloud"
+      ],
+      "imports": [],
+      "source": "e3-cloud --version                        # e3-cloud 1.1.1 (east 1.0.101, e3 1.0.101): this CLI, and the east and e3 it is built with\ne3-cloud --version --json                 # {\"e3Cloud\":\"1.1.1\",\"east\":\"1.0.101\",\"e3\":\"1.0.101\"}\ne3-cloud whoami https://e3.example.com\n#   sub: …  email: …  admin: false\n#   deployment: e3-cloud 1.1.1, e3 1.0.101\n#   staged for: e3 1.0.102 (apps deployed with --for-platform)   (only when a bundle is staged for a next e3)\n#   cli: e3-cloud 1.1.1 (east 1.0.101, e3 1.0.101)\n#   note: …   only where the CLI's e3 and the deployment's differ: a package exported with a newer e3 than the deployment's is refused\n# A project builds with the e3 cloud release the deployment runs, beside the east and e3 it pins (npm view @elaraai/e3-cloud-files@1.1.1 peerDependencies)",
       "languages": [
         "typescript"
       ]
@@ -909,7 +1035,10 @@
         "restore",
         "backup-pull",
         "commit",
-        "audit"
+        "audit",
+        "pending",
+        "$seed",
+        "seeded from a file"
       ],
       "imports": [],
       "source": "e3-cloud records list https://e3.example.com/repos/acme production\ne3-cloud records history https://e3.example.com/repos/acme production orders --limit 50\ne3-cloud records show https://e3.example.com/repos/acme production orders <commit> -o orders.beast2\ne3-cloud records backup https://e3.example.com/repos/acme production orders --note \"before the import\"\ne3-cloud records rollback https://e3.example.com/repos/acme production orders <commit>    # a new commit holding that state",
@@ -990,6 +1119,7 @@
         "beast2",
         "typed",
         "unchanged",
+        "dataset",
         "e3-cloud"
       ],
       "imports": [],
@@ -998,6 +1128,42 @@
         "typescript"
       ]
     },
+    {
+      "id": "e3-cloud-cli:static:files-push-dataset",
+      "skill": "e3-cloud-cli",
+      "package": "e3-cloud-cli",
+      "file": "static",
+      "suite": "e3-cloud files",
+      "test": "Pushing a workspace's dataset (a task's output, an input or a record) into a source as the file of its value, with no file kept by hand: dataset:<workspace>.<name>, read from the repository --from names (a local path or a repository URL), matched by its name or --as, unchanged for the same stored value, refused in its row when unassigned or not found; a seed's history names the dataset",
+      "keywords": [
+        "files",
+        "push",
+        "dataset",
+        "dataset:",
+        "--from",
+        "task output",
+        "input",
+        "record",
+        "seed",
+        "$seed",
+        "--reset",
+        "--as",
+        "unchanged",
+        "unassigned",
+        "not_found",
+        "local repository",
+        "local workspace",
+        "e3 dataset get",
+        "beast2",
+        "e3-dataset",
+        "e3-cloud"
+      ],
+      "imports": [],
+      "source": "# A local workspace's task output seeding a deployed workspace's record: matched by its name (record:customers), put at its mapping's key\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive\n#   dataset:dev.customers (task output)  → record:customers  seed  3 MiB  put  $init #1  12,004 rows\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive   # the same stored value again: unchanged\ne3 dataflow run ./archive dev                                    # its value changes\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive   # $seed #2 while nothing has mutated the record; kept once something has\ne3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive --reset customers   # its state again, over its mutations\n# --from defaults as e3's [repo] does ($E3_REPO, then .); a repository URL reads a deployed workspace's dataset with your e3 login\ne3-cloud files push ./repo dev dataset:production.price_list --from https://e3.example.com/repos/acme --as prices   # any file or latest mapping, by --as\n# Its bytes are the value's beast2, as `e3 dataset get -f beast2` writes it, read a segment at a time and checked against the mapping's type\n# before anything is put; under a latest prefix it is put as <name>.beast2; a folder or a listing takes no dataset. Refused in its row, the\n# rest going on: unassigned (a task output not produced since the last deploy, an input never set, a record with no state), not_found, ambiguous.\n# The object carries e3-dataset and e3-dataset-hash metadata; the history reads\n# \"Initialised from customers.beast2 (12,004 rows), from dev.customers at 3f9a2b1c4d5e\"",
+      "languages": [
+        "typescript"
+      ]
+    },
     {
       "id": "e3-cloud-client:static:basics",
       "skill": "e3-cloud-client",
@@ -1023,6 +1189,32 @@
         "typescript"
       ]
     },
+    {
+      "id": "e3-cloud-client:static:versions",
+      "skill": "e3-cloud-client",
+      "package": "e3-cloud-client",
+      "file": "static",
+      "suite": "@elaraai/e3-cloud-client platform",
+      "test": "Which releases a deployment runs, from code: its e3 cloud release, the e3 its platform and runners run, and each next e3 an app's bundle is staged for; null from a deployment that predates it",
+      "keywords": [
+        "platformVersions",
+        "PlatformVersions",
+        "version",
+        "release",
+        "e3 version",
+        "e3Cloud",
+        "staged",
+        "deployment",
+        "/api/platform"
+      ],
+      "imports": [
+        "import { platformVersions } from '@elaraai/e3-cloud-client';"
+      ],
+      "source": "const versions = await platformVersions(url, options);   // anyone signed in may ask\nif (versions === null) console.log('the deployment predates it: it names no release');\nelse {\n  console.log(versions.e3Cloud.type === 'some' ? versions.e3Cloud.value : 'release not stated', versions.e3, versions.staged.join(', '));\n  // A package exported with a newer e3 than versions.e3 is refused: build with the e3 cloud release the deployment runs\n}",
+      "languages": [
+        "typescript"
+      ]
+    },
     {
       "id": "e3-cloud-client:static:app-deploy",
       "skill": "e3-cloud-client",
@@ -1109,6 +1301,50 @@
       "languages": [
         "typescript"
       ]
+    },
+    {
+      "skill": "e3-cloud-client",
+      "package": "e3-cloud-client",
+      "file": "static",
+      "id": "e3-cloud-client:static:files",
+      "suite": "@elaraai/e3-cloud-client files",
+      "test": "Files from code: deploy a workspace's declarations, bind a source, sync named targets (a seeded record reset) and wait for the sync's report, read what each mapping holds, and push a file from disk (plan, upload through the platform, sync), or a workspace's dataset as the file of its value",
+      "keywords": [
+        "getFiles",
+        "deployFiles",
+        "bindFilesSource",
+        "startFilesSync",
+        "filesSyncWait",
+        "planFilesPush",
+        "completeFilesPush",
+        "FilesPushBytes",
+        "uploadFilesPush",
+        "FilesTarget",
+        "targets",
+        "reset",
+        "pending",
+        "seeded",
+        "record",
+        "mutation",
+        "push",
+        "dataset",
+        "unchanged",
+        "refused",
+        "retaken",
+        "workspace_protected"
+      ],
+      "imports": [
+        "import { createReadStream } from 'node:fs';",
+        "import { stat } from 'node:fs/promises';",
+        "import { none, some, variant } from '@elaraai/east';",
+        "import { bindFilesSource, deployFiles, filesSyncWait, getFiles, planFilesPush, startFilesSync, uploadFilesPush, type FilesPushBytes } from '@elaraai/e3-cloud-client';",
+        "import { filesPushRefusalText, filesTargetText } from '@elaraai/e3-cloud-types';",
+        "import manifest from './files.js';   // export default Files.manifest([upload])"
+      ],
+      "source": "// The declarations (checked against the package the workspace runs), then where the source's files are\nconst deployed = await deployFiles(url, 'acme', 'staging', manifest, options);\nif (deployed.type === 'refused') throw new Error(deployed.value.problems.map((p) => p.type).join(', '));\nawait bindFilesSource(url, 'acme', 'staging', { source: 'upload', url: 's3://partner-drop/acme/', region: none, profile: none, latest: none }, options);\n\n// A sync of two targets: the seeded record's file taken as its state again (reset), and the fed mutation's new files\nconst start = await startFilesSync(url, 'acme', 'staging', {\n  targets: [variant('record', 'customers'), variant('mutation', { record: 'price_book', mutation: 'load_prices' })],\n  reset: ['customers'],\n}, options);\nconst id = start.value;   // started, or running: the sync under way, waited on the same way\nconst job = await filesSyncWait(url, 'acme', 'staging', id, options, { deadlineMs: 10 * 60_000 });\nfor (const m of job.report.type === 'some' ? job.report.value.mappings : []) {\n  console.log(filesTargetText(m.target), m.updated ? `written (commit ${m.commit.type === 'some' ? m.commit.value.slice(0, 12) : 'none'})` : 'as it was', m.refused.length === 0 ? '' : `refused ${m.refused[0]!.key}`);\n}\n\n// What each mapping holds now; a record not yet seeded is pending\nconst files = await getFiles(url, 'acme', 'staging', options);\nconsole.log(files.status.mappings.map((m) => `${filesTargetText(m.target)}: ${m.pending ? 'pending' : m.holds.type === 'some' ? m.holds.value.key : 'nothing yet'}`).join(' · '));\n\n// A push from disk: the plan says per file where it goes and how to upload it; uploadFilesPush puts it through the platform\n// (one PUT bound to its SHA-256, or a multipart upload it completes), then one sync of the targets put\nconst path = 'data/customers.beast2';\nconst size = (await stat(path)).size;\nconst plan = await planFilesPush(url, 'acme', 'staging', {\n  files: [{ name: 'customers.beast2', directory: none, size: BigInt(size), sha256, type: some(customerBookType), dataset: none }],   // sha256: hex; type: its beast2 header's\n  as: none,\n}, options);\nconst bytes: FilesPushBytes = { size, ranged: true, read: (start) => createReadStream(path, { start }) };   // a file reads from any offset\nfor (const f of plan.files) {\n  if (f.outcome.type === 'refused') console.warn(f.name, filesPushRefusalText(f.outcome.value));\n  else if (f.outcome.type === 'put') await uploadFilesPush(url, 'acme', 'staging', plan, f.outcome.value, bytes, options);   // an `external` put throws: your own credentials\n}\nawait startFilesSync(url, 'acme', 'staging', { targets: plan.files.flatMap((f) => (f.outcome.type === 'put' ? [f.outcome.value.target] : [])) }, options);\n// A workspace's dataset is offered as the file of its value: dataset: some({ workspace: 'dev', name: 'customers', hash }), its type the value's,\n// its bytes the value's beast2 as `e3 dataset get -f beast2` writes it, streamed (ranged: false: never held whole) and matched by its name.\n// `e3-cloud files push … dataset:dev.customers --from <repo>` does all of it",
+      "languages": [
+        "typescript"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/e3-cloud-claude-plugin",
-  "version": "1.0.97",
+  "version": "1.1.1",
   "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, files from buckets as inputs with @elaraai/e3-cloud-files, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/skills/e3-cloud-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e3-cloud-cli
-description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps` (a release carries the package, the apps and the Files declarations; the target keeps its data and bindings), `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`), (8) Files — a solution's inputs from files in a bucket: `e3-cloud files deploy|bind|sync|status`, given a local repository's path or a repository URL (the e3-cloud-files skill declares and decodes them), (9) Walking a solution through its life, step by step — starting it, adding a staging, developing an app's pages, changing the package's tasks and inputs, migrating a record, Files, rehearsing and releasing, rolling back, an emergency change to production, people and roles, schedules, secrets and compute, feedback, the platform's next e3, and retiring an app or a workspace."
+description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares), checking who you are and which e3 cloud release and e3 the deployment runs (`e3-cloud whoami SERVER`), and which this CLI is built with (`e3-cloud --version`, `--json`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps` (a release carries the package, the apps and the Files declarations; the target keeps its data and bindings), `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`), (8) Files — a solution's inputs from files in a bucket: `e3-cloud files deploy|bind|sync|push|status`, given a local repository's path or a repository URL, and `files push` of files from disk or of a workspace's dataset as the file of its value (`dataset:WORKSPACE.NAME`, `--from` a local repository or a URL) (the e3-cloud-files skill declares and decodes them), (9) Walking a solution through its life, step by step — starting it, adding a staging, developing an app's pages, changing the package's tasks and inputs, migrating a record, Files, rehearsing and releasing, rolling back, an emergency change to production, people and roles, schedules, secrets and compute, feedback, the platform's next e3, and retiring an app or a workspace."
 ---
 
 # e3-cloud — the e3 cloud CLI (@elaraai/e3-cloud-cli)
@@ -38,7 +38,7 @@ Nothing is injected for you; the search is the step.
 ```bash
 npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli
 e3 auth login https://e3.example.com
-e3-cloud whoami https://e3.example.com
+e3-cloud whoami https://e3.example.com     # you, the release and e3 the deployment runs, and this CLI's
 
 # An app: build its bundle, check it, deploy it
 e3-cloud app build src/apps/ops.tsx
@@ -159,9 +159,9 @@ e3 dataflow run URL staging
 
 ### 5. Migrate a record
 
-A record's new type comes with a migration in the package: e3's
-`e3.migration.value`, `rows` or `rekey`, each step naming the one before it
-with `after` (the e3 skill). Then, in staging:
+A record's new type comes with a migration in its own declaration: a step
+added at the end of its `migrations` (`migration.value`, `rows` or `rekey`,
+each named, the list's order the chain; the e3 skill). Then, in staging:
 
 ```bash
 e3-cloud records backup URL staging orders --note "before orders v2"
@@ -189,6 +189,9 @@ e3-cloud release URL staging production --plan
 e3-cloud files deploy URL staging src/files.ts
 e3-cloud files bind   URL staging upload s3://bucket/acme/staging/
 e3-cloud files sync   URL staging
+e3-cloud files push   URL staging ./data/prices.beast2 ./data/customers.beast2    # from disk: matched by name (or --as), put, synced
+e3-cloud files push   URL staging dataset:dev.customers --from ./repo              # a local workspace's dataset, as the file of its value
+e3-cloud files sync   URL staging --target record:customers --reset customers     # named targets; a seeded record's file as its state again
 e3 dataflow run URL staging
 ```
 
@@ -313,8 +316,9 @@ e3-cloud app deploy URL staging --from-source src/apps/ops.tsx --for-platform 1.
 e3-cloud release URL staging production
 ```
 
-- Build with the next release's packages and stage the bundle beside the
-  live app: it goes live when the platform moves to that e3. A release
+- Build with the e3 cloud release built with the next e3 (its packages pin
+  it) and stage the bundle beside the live app: it goes live when the
+  platform moves to that e3. A release
   carries staging's staged bundles, so production gets them through its
   staging.
 
@@ -409,8 +413,18 @@ a repository URL:
   changes them, and a source may be bound before a release brings the
   declarations that read it.
 - `files sync <repo> <ws>` reads only files whose ETag or size changed and
-  writes only inputs whose files changed; `--input`, `--dry-run`. It doesn't
+  writes only inputs whose files changed; `--target`, `--reset`, `--dry-run`. It doesn't
   run the dataflow: `e3 dataflow run` does, and the sync prints the command.
+- `files push <repo> <ws> <path…>` puts files from disk, or datasets
+  (`dataset:<ws>.<name>`: a task's output, an input or a record, read from
+  the repository `--from` names, a local path or a URL, default `$E3_REPO`
+  then `.`), into the source each one's mapping reads, then syncs what was
+  put: matched by name or `--as`, checked against the mapping's type before
+  anything is put, `unchanged` when the source holds it already, refused in
+  its row otherwise (`unassigned`, `not_found`, `no_mapping`, `type_mismatch`,
+  …); `--reset`, `--dry-run`, `--profile` (a bucket the platform doesn't
+  write). A seed's or feed's history names the file, and the dataset it was
+  pushed from.
 - `files status <repo> <ws>`: the declarations, the bindings, the last sync.
 
 ## Traps
@@ -427,5 +441,11 @@ a repository URL:
   hasn't bound: bind it in the target first.
 - `secrets set` reads the value from stdin unless `--value` is given; the
   next run reads the new value.
-- The version is the @elaraai lockstep: use the CLI of the release your
-  deployment runs.
+- The version is e3 cloud's own, not e3's: use the CLI of the e3 cloud
+  release your deployment runs, beside e3's CLI of the e3 that release is
+  built with (its dependencies pin it). `e3-cloud --version` prints
+  `e3-cloud 1.1.1 (east 1.0.101, e3 1.0.101)` (`--json`:
+  `{"e3Cloud":…,"east":…,"e3":…}`); `e3-cloud whoami <server>` prints the
+  deployment's `deployment: e3-cloud 1.1.1, e3 1.0.101` beside it, and a
+  `note:` where the e3s differ: a package exported with a newer e3 than the
+  deployment's is refused.

package/skills/e3-cloud-client/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e3-cloud-client
-description: "@elaraai/e3-cloud-client — drive an e3 cloud deployment from TypeScript. Use when: (1) Calling a deployment from code with a token (`whoami`, `RequestOptions`, `ApiError`), (2) Managing a repository's people and business roles (`repoUsers`, `addUser`, `removeUser`, `repoInvitations`, `listRoles`, `putRole`, `myAccess`), (3) Deploying apps from code — `appUpload`, `appDeploy` / `appsDeploy` and `appDeployWait`, `appList`, `appGet`, `appVersions`, `appRemove` — and reading a refusal (`appProblemsText`), (4) Staging, releasing and rolling back — `addStaging` / `stopStaging` (a staging protects the workspace it releases to), `releaseWorkspace`, `rollbackWorkspace` (a plan first, `releasePlanRefusalLines`), `workspaceHistory`, `getRepositoryReleaseSettings`, (5) Secrets, schedules and task configs (`putSecret`, `listSecrets`, `setSchedule`, `setCompute`, `setTimeout`), (6) Records' history and backups (`recordAudit`, `createRecordBackup`, `restoreRecordBackup`) and feedback (`listFeedback`, `closeFeedback`)."
+description: "@elaraai/e3-cloud-client — drive an e3 cloud deployment from TypeScript. Use when: (1) Calling a deployment from code with a token (`whoami`, `RequestOptions`, `ApiError`), (2) Managing a repository's people and business roles (`repoUsers`, `addUser`, `removeUser`, `repoInvitations`, `listRoles`, `putRole`, `myAccess`), (3) Deploying apps from code — `appUpload`, `appDeploy` / `appsDeploy` and `appDeployWait`, `appList`, `appGet`, `appVersions`, `appRemove` — and reading a refusal (`appProblemsText`), (4) Staging, releasing and rolling back — `addStaging` / `stopStaging` (a staging protects the workspace it releases to), `releaseWorkspace`, `rollbackWorkspace` (a plan first, `releasePlanRefusalLines`), `workspaceHistory`, `getRepositoryReleaseSettings`, (5) Secrets, schedules and task configs (`putSecret`, `listSecrets`, `setSchedule`, `setCompute`, `setTimeout`), (6) Records' history and backups (`recordAudit`, `createRecordBackup`, `restoreRecordBackup`) and feedback (`listFeedback`, `closeFeedback`), (7) Files from code — `getFiles`, `deployFiles`, `bindFilesSource`, `startFilesSync` and `filesSyncWait`, and a push: `planFilesPush`, `uploadFilesPush` (a file from disk by ranges, or a workspace's dataset as its value streams, with its type and where it came from), `completeFilesPush`, (8) Which releases a deployment runs (`platformVersions`: its e3 cloud release, its e3, the next e3s bundles are staged for)."
 ---
 
 # @elaraai/e3-cloud-client
@@ -67,10 +67,64 @@ try {
   and its `undoes` lists forced changes it undoes. `rollbackWorkspace` takes
   an entry of `workspaceHistory`.
 
+## Files
+
+- `getFiles(url, repo, ws, options)` answers a workspace's Files: its
+  declarations (`manifest`), where each source is bound (`bindings`), the
+  last sync, a sync under way, and `status` — per mapping, what it holds and
+  whether its record is `pending` (seeded from a file, its file not yet
+  arrived).
+- `deployFiles(url, repo, ws, manifest, options `{ dryRun?, force? }`)` deploys declarations
+  (`Files.manifest(...)` from `@elaraai/e3-cloud-files`): `deployed` with
+  the targets the next sync takes again whole (`retaken`), `checked` for a
+  dry run, or `refused` with every problem. A workspace with a staging
+  refuses it (`workspace_protected`) unless an admin forces it.
+- `bindFilesSource(url, repo, ws, binding, options)` says where a source's
+  files are (`s3://bucket/prefix/`): `bound` with what the next sync takes
+  again, or `refused` (a bucket the deployment does not let the repository
+  bind). Bindings are each workspace's own; a release never changes them.
+- `startFilesSync(url, repo, ws, { dryRun?, targets?, reset? }, options)`
+  answers `started` with the sync's id, or `running` with the one under way;
+  `filesSyncWait(url, repo, ws, id, options, { deadlineMs?, refresh?, signal? })`
+  polls it to its end and answers the job, its `report` per target (what was
+  taken, the commit a seed or feed made, what was refused and why, what
+  waits). `targets` are `variant('input', name)`, `variant('record', name)`
+  or `variant('mutation', { record, mutation })`; `reset` names seeded
+  records whose file is taken as their state again.
+- `planFilesPush(url, repo, ws, { files, as }, options)` plans a push of
+  files (each offered with its name, size, SHA-256 and beast2 header type,
+  and `dataset: some({ workspace, name, hash })` for a workspace's dataset
+  offered as the file of its value): per file `put` with its key and how to
+  upload it — `single` (one PUT with the plan's headers), `multipart` (a URL
+  per part, then a completion) or `external` (your own credentials) —
+  `unchanged`, or `refused` with why (`filesPushRefusalText`). A dataset is
+  matched by its name, to the `file` or `latest` mapping filling the input
+  or record of that name.
+- `uploadFilesPush(url, repo, ws, plan, put, bytes, options, refresh?)`
+  uploads one put through the platform, `bytes` a `FilesPushBytes`
+  (`{ size, read(start), ranged }`): a file on disk is `ranged` (its parts
+  sent four at a time, each read from its start), a dataset's value streams
+  from its repository (`ranged: false`, parts one after another, never held
+  whole). A multipart upload is completed under the object's key in its
+  bucket (`completeFilesPush`); a source that throws as its bytes end (a
+  dataset rewritten while it was read) has its last bytes held back, so
+  nothing other than the planned bytes is ever stored. Then sync the targets
+  put. The CLI's `files push` does all of this.
+
+## Versions
+
+- `platformVersions(url, options)` answers what a deployment runs:
+  `{ e3Cloud: some('1.1.1'), e3: '1.0.101', staged: [...] }` (the next e3s
+  an app's bundle is staged for, in the repositories the caller manages), or
+  `null` from a deployment that predates it. A package exported with a newer
+  e3 than the deployment's is refused: compare it with the e3 your project
+  builds with before a deploy.
+
 ## Traps
 
 - The URL is the deployment's origin, not `…/api`: the client adds the path.
 - A refusal of a release or an app deploy is an answer (`refused`), not a
   throw; a request the server cannot take at all throws `ApiError`.
-- The version is the @elaraai lockstep: use the client of the release the
-  deployment runs.
+- The version is e3 cloud's own, shared by every e3 cloud package and
+  independent of e3's: use the client of the e3 cloud release the deployment
+  runs, beside the east and e3 it pins.

package/skills/e3-cloud-files/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e3-cloud-files
-description: "Files for e3 cloud — a solution's inputs that come from files in a bucket (s3://bucket/prefix/), declared in its code and synced when asked, the same on a local repository and a deployed workspace. Use when: (1) Declaring which inputs a bucket's files fill with Files.source(name) and its file, latest, folder and listing, then Files.manifest([...]) as a module's default export, (2) Decoding what arrives in a task: a Blob (file, latest), a Dict of path to Blob (folder) or a listing of sizes, times and ETags, as East's JSON, CSV or text, (3) Deploying the declarations to a workspace and binding each source to s3://bucket/prefix/ with e3-cloud files deploy and bind, (4) Syncing what changed with e3-cloud files sync, locally with your own cloud profile (--profile, --latest), then running the dataflow with e3 dataflow run, (5) Reading a refusal: declarations that don't fit the package (FilesDeclarationError, a deploy's problems), an unbound source, a file over its limit, a protected workspace (workspace_protected), (6) Moving declarations to production through staging: a release carries them with the package and apps, a rollback restores them, a copy brings bindings and what each input took, and production's bindings stay its own, (7) Reading Files' East types (FilesManifestType, FilesBindingType, FilesSyncReportType — @elaraai/e3-cloud-types), (8) Taking a beast2 file in as an input of its type with no task in between: file or latest with a type, a collection of any size, (9) Feeding a record's mutation from files with source.mutation(def, spec), each new file applied once, (10) Pushing files from disk into a source and taking them in with e3-cloud files push, matched by name or --as, dry-run, unchanged, (11) Syncing or resetting particular targets with --target and --reset."
+description: "Files for e3 cloud — a solution's inputs that come from files in a bucket (s3://bucket/prefix/), declared in its code and synced when asked, the same on a local repository and a deployed workspace. Use when: (1) Declaring which inputs a bucket's files fill with Files.source(name) and its file, latest, folder and listing, then Files.manifest([...]) as a module's default export, (2) Decoding what arrives in a task: a Blob (file, latest), a Dict of path to Blob (folder) or a listing of sizes, times and ETags, as East's JSON, CSV or text, (3) Deploying the declarations to a workspace and binding each source to s3://bucket/prefix/ with e3-cloud files deploy and bind, (4) Syncing what changed with e3-cloud files sync, locally with your own cloud profile (--profile, --latest), then running the dataflow with e3 dataflow run, (5) Reading a refusal: declarations that don't fit the package (FilesDeclarationError, a deploy's problems), an unbound source, a file over its limit, a protected workspace (workspace_protected), (6) Moving declarations to production through staging: a release carries them with the package and apps, a rollback restores them, a copy brings bindings and what each input took, and production's bindings stay its own, (7) Reading Files' East types (FilesManifestType, FilesBindingType, FilesSyncReportType — @elaraai/e3-cloud-types), (8) Taking a beast2 file in as an input of its type with no task in between: file or latest with a type, a collection of any size, (9) Feeding a record's mutation from files with source.mutation(def, spec), def one its record declares (priceBook.mutations.load_prices), each new file applied once, (10) Pushing files from disk into a source and taking them in with e3-cloud files push, matched by name or --as, dry-run, unchanged, or a workspace's dataset (a task's output, an input, a record) as the file of its value with dataset:workspace.name and --from, local or remote at either end, (11) Seeding a record from a file with source.record(name, type, spec, parts): e3.record with no initial value, declared whole with its indexes, mutations and migrations, pending until its file, its tasks waiting meanwhile, (12) Syncing or resetting particular targets with --target and --reset."
 ---
 
 # e3-cloud-files — files as e3 inputs
@@ -11,8 +11,9 @@ are, a bucket and a prefix, and `e3-cloud files sync` brings in what changed:
 on a local repository with your own cloud credentials, in the cloud with the
 platform's read-only role. A file arrives as it is, a `Blob`, and a task
 decodes it; or, named with a type, a beast2 file arrives as the value it
-holds, with no task in between. `e3-cloud files push` puts files from disk
-into a source and takes them in. Nothing polls: a sync runs when someone asks.
+holds, with no task in between. `e3-cloud files push` puts files from disk,
+or a workspace's datasets as the files of their values, into a source and
+takes them in. Nothing polls: a sync runs when someone asks.
 
 Read `README.md` for the author's guide; this file is the short form.
 
@@ -70,7 +71,8 @@ What do you need?
 │   ├─ A beast2 file as its value     → source.file(input, { key, type: ArrayType(Row) })  input: Array<Row>, no task between
 │   ├─ The newest of a folder         → source.latest(input, { prefix, include? })     input: Blob, the greatest key
 │   ├─ The newest, typed              → source.latest(input, { prefix, include?, type })
-│   ├─ Feed a record's mutation       → source.mutation(def, { key } | { prefix, include? })  each new file calls it once
+│   ├─ A record's first state         → source.record(name, type, { key } | { prefix, include? }, parts?)  e3.record(name, type, parts): pending until its file
+│   ├─ Feed a record's mutation       → source.mutation(record.mutations.<name>, { key } | { prefix, include? })  every new file, in key order, once
 │   ├─ Every file of a folder         → source.folder(input, { prefix, include? })     input: Dict<String, Blob> by path
 │   ├─ A folder's files, not bytes    → source.listing(input, { prefix, include? })    input: Dict<String, {size, modified, etag}>
 │   ├─ Subfolders' files too          → include: '**/*.csv' ('*.csv' is the top level only)
@@ -88,6 +90,7 @@ What do you need?
 │   │   └─ Locally only               → --profile <aws profile>, --latest <n> (each folder's n greatest keys)
 │   ├─ Bring in what changed          → e3-cloud files sync <repo> <ws> [--target t…] [--reset record…] [--dry-run]
 │   ├─ Put files from disk            → e3-cloud files push <repo> <ws> <file|dir>… [--as target] [--dry-run] [--profile p]
+│   ├─ Push a workspace's dataset     → e3-cloud files push <repo> <ws> dataset:<ws>.<name>… [--from <repo>] (a task's output, an input, a record)
 │   ├─ What is declared, bound, held  → e3-cloud files status <repo> <ws> (each mapping, its type, what it holds, pending)
 │   └─ Run the dataflow on it         → e3 dataflow run <repo> <ws> (a sync doesn't run it)
 ├─ Production: a workspace with a staging (a deployed repository's URL)
@@ -118,6 +121,9 @@ export const rates  = upload.file('rates', { key: 'rates.json' });
 export const stock  = upload.latest('stock', { prefix: 'stock/', include: '*.json' });    // input: Blob, the greatest key
 export const orders = upload.folder('orders', { prefix: 'orders/', include: '*.json' });  // input: Dict<String, Blob>
 export const orderFiles = upload.listing('order_files', { prefix: 'orders/' });           // input: each file's size, modified, etag
+export const prices = upload.file('prices', { key: 'prices.beast2', type: ArrayType(Price) });      // input: Array<Price>: the beast2 file's value, any size
+export const customers = upload.record('customers', CustomerBook, { key: 'customers.beast2' });    // a record, e3.record('customers', CustomerBook): pending until its file
+upload.mutation(priceBook.mutations.load_prices, { prefix: 'deltas/', include: '*.beast2' });       // each new delta file fed to the record's mutation, in key order
 
 export default Files.manifest([upload]);       // what e3-cloud files deploy deploys
 ```
@@ -127,9 +133,22 @@ export default Files.manifest([upload]);       // what e3-cloud files deploy dep
   `file` or `latest` with a `type` is an input of that type: the file must be
   beast2 of it (`encodeBeast2For(T)`, east-py, `e3 convert`), a collection of
   any size, checked by its header before any other byte is read.
-- `source.mutation(def, spec)` feeds a record's mutation: `def` is the
-  package's `e3.mutation.reduce` or `edit` taking exactly one argument, and
-  each new file is applied once, by its hash.
+- `source.record(name, type, spec, parts?)` is `e3.record(name, type, parts)`
+  with no initial value. It is declared whole: its indexes, mutations and
+  migrations are `parts`, as `e3.record` takes them
+  (`{ mutations: (mutation) => ({ set_tier: mutation.reduce(fn) }) }`), and an
+  initial value is refused. It is pending until its file arrives, which is
+  its first state (`$init`; nothing runs on an empty state first, and the
+  tasks over it wait as on an unset input, the run completing without them).
+  A changed file while nothing has mutated it since is its state again
+  (`$seed`); mutated since, it is kept until `files sync --reset <record>`.
+- `source.mutation(def, spec)` feeds a record's mutation: `def` is one the
+  record declares, `record.mutations.<name>`, a `reduce` or an `edit` taking
+  exactly one argument. Every new file the spec selects (one key, or each
+  under the prefix its glob matches) is applied in key order, once by its
+  bytes' hash, so the same bytes under another name are applied no more; a
+  file the mutation refuses holds the ones after it until it changes; a busy
+  record leaves the file to the next sync.
 - Keys and prefixes are relative to where a workspace binds the source; a
   prefix is `''` or ends with `/`.
 - `include` is a glob over the path under the prefix: `*` within one folder,
@@ -158,7 +177,7 @@ file's path under the prefix, in path order.
 e3-cloud files deploy <repo> <workspace> src/files.ts [--dry-run]
 e3-cloud files bind   <repo> <workspace> upload s3://bucket/prefix/ [--region r] [--profile p] [--latest n]
 e3-cloud files sync   <repo> <workspace> [--target name|record:r|mutation:r.m ...] [--reset record...] [--dry-run]
-e3-cloud files push   <repo> <workspace> <file|dir>... [--as target] [--reset record...] [--dry-run] [--profile p]
+e3-cloud files push   <repo> <workspace> <file|dir|dataset:ws.name>... [--from repo] [--as target] [--reset record...] [--dry-run] [--profile p]
 e3-cloud files status <repo> <workspace>
 e3 dataflow run <repo> <workspace>
 ```
@@ -168,7 +187,38 @@ name, a `latest` under its prefix, a directory to the `folder`; `--as` names
 one), checks its type and size, puts it where the source is bound (the
 platform signs the upload into the deployment's own bucket, bound to the
 file's SHA-256; your own credentials elsewhere), then syncs what was put. A
-file the source holds already is `unchanged`.
+file the source holds already is `unchanged`; refused: `no_mapping`,
+`ambiguous` (name the target with `--as`), `not_included` (the mapping's
+glob leaves it out), `not_latest` (a greater key would shadow it), a typed
+mapping's file of another type or no beast2, one over the limit. The report
+numbers a record's seeds: `$init #1`, `$seed #2`, …
+
+`dataset:<workspace>.<name>` pushes a value a workspace holds (a task's
+output, an input or a record, by its name) as the file of its value would,
+with no file kept by hand: its bytes are the value's beast2 (as
+`e3 dataset get -f beast2` writes it), read a segment at a time from the
+repository `--from` names (a local path or a repository URL; default
+`$E3_REPO`, then `.`, as e3's `[repo]`). It goes to the `file` or `latest`
+mapping filling the input or record of its name, else `--as` names one; it
+is put at the `file`'s key, or under the `latest`'s prefix as
+`<name>.beast2`; a `folder` or `listing` takes none. The same stored value
+is `unchanged`; refused in their rows: `unassigned` (a task output not
+produced since the workspace's last deploy, an input never set, a record
+with no state), `not_found`, `ambiguous` (two of the workspace's datasets
+have the name); a dataset a run rewrites while it uploads fails in its row
+(push again). The object carries `e3-dataset` and `e3-dataset-hash`
+metadata, and a seed's or feed's history names the dataset: "Initialised
+from customers.beast2 (12,004 rows), from dev.customers at 3f9a2b1c4d5e".
+Files, directories and datasets mix in one push.
+
+```bash
+# A local workspace's task output, seeding a deployed workspace's record
+e3-cloud files push https://e3.example.com/repos/acme dev dataset:dev.customers --from ./archive
+```
+
+`--target` names an input, `record:<name>` or `mutation:<record>.<name>`
+(split at its last dot); `--reset <record>` takes a seeded record's file as
+its state again, whatever mutated it since.
 
 `<repo>` is a local repository's path or a repository URL. Deploy the package
 first (`e3 workspace deploy`), then the declarations, which are checked
@@ -189,9 +239,25 @@ keeps only each folder's n greatest keys.
   (`type_mismatch` with both types, `not_beast2`): the input keeps its value.
   A typed value that is no collection is at most 1 GiB; a collection's
   segments at most 64 MiB (`segment_too_large`: write it again).
-- A seeded record (`upload.record`) waits for the e3 release that lets a
-  record be declared with no initial value; the rest of typed files, feeds
-  and push is here now.
+- A seeded record (`upload.record(name, type, { key })`) is pending until
+  its file, which is its first state (`$init`); a changed file seeds it
+  again while unmutated (`$seed`), `--reset` does whatever was done since;
+  the tasks over it wait meanwhile. The workspace page shows it Pending, its
+  page says what seeds it, `files status` prints `pending`; its seeds read
+  "Initialised from customers.beast2 (12,004 rows)" / "Seeded again from …"
+  in its history (the record page, `e3-cloud records history`), a feed names
+  its file. A deploy that cannot keep it (its type changed) under
+  `--schema reset` unassigns it: pending again, seeded by the next version's
+  file.
+- A dataset pushed to a seeded record seeds it like a file: again while
+  unmutated (`$seed #n`), `kept` once mutated, over its mutations with
+  `--reset`. A dataset whose value is unchanged since the last push is
+  `unchanged`, nothing put; one never produced since the workspace's last
+  deploy is `unassigned`: run the dataflow first.
+- A record is declared whole: a fed mutation is one its record declares
+  (`priceBook.mutations.load_prices`), and a seeded record's indexes,
+  mutations and migrations are `upload.record`'s `parts`; an initial value
+  there is refused, its file being its first state.
 - A file over 1 GiB less 64 KiB (`file`, `latest`), or over 64 MiB less
   64 KiB in a folder, is refused and named in the report, never truncated.
   So is a file the sync can't read (archived, under a key it may not use,
@@ -209,7 +275,9 @@ keeps only each folder's n greatest keys.
 - Bindings never travel with a release; a copy carries them. A staging
   started as a copy of production reads production's files until you bind it
   elsewhere.
-- The version is the @elaraai lockstep: use the same version as east and e3.
+- The version is e3 cloud's own, not e3's: install the release built with the
+  e3 the deployment runs, its peers (east, e3) at exactly the versions it
+  names, and the `e3-cloud` CLI of the same release.
 
 ## Related skills
 

package/skills/e3-cloud-ui/SKILL.md

@@ -64,7 +64,10 @@ const overview = Page('overview', { title: 'Overview', icon: 'gauge-high' },
 - The function's **one argument is the page's params** (or none). Never write
   the type separately: TypeScript takes it from the function.
 - Bind data exactly as a `ui()` body does: `Data.bind`, `Data.bindPaged`,
-  `Func.bind`, `Record.bind`. Pass the defs, never names.
+  `Func.bind`, `Record.bind`. Pass the defs, never a dataset's or a
+  function's name; a record's mutations and indexes are named as the record
+  declares them: `Record.bind(orders, ['approve'])`,
+  `Data.bindPaged(orders, { index: 'by_line' })`.
 - `meta.parent` makes the crumbs and lights the menu item.
 - Bind event handlers once: `const go = $.const(East.function([], NullType, $ => { $(Nav.go(line, key)); }))`.
 
@@ -103,6 +106,12 @@ on the workspace fits.
 - A body written without the thunk can only link to pages defined above it.
 - A page that writes a task's output or a record through `Data.bind` is
   refused: write inputs; change records through their mutations.
+- A record is declared whole: its indexes, mutations and migrations in its
+  own `e3.record(name, type, { initial, indexes, mutations, migrations })`.
+  `e3.package` takes the record, never one of its parts.
 - `Page.task` needs a task in the `ui` role (`ui()`), and its output shows only
   after the workspace's next dataflow run.
-- The version is the @elaraai lockstep: use the same version as east and e3.
+- The version is e3 cloud's own, not e3's: install the release built with the
+  e3 the deployment runs, its peers (east, east-ui, e3, e3-ui) at exactly the
+  versions it names. An app built with another e3 than the platform's is
+  refused, naming both.