@eum-agent/file-explorer 0.0.0-stage → 1.0.1

package/dist/schema.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+//#region src/schema.ts
+/** The provider's sole wire declarations; browser and server infer types from these schemas. */
+/** A literal safe host filename or explicit identity segment. */
+const SegmentSchema = z.string().min(1).max(1024).refine((value) => value !== "." && value !== ".." && [...value].every((character) => character !== "/" && character !== "\\" && character.charCodeAt(0) > 31 && character.charCodeAt(0) !== 127), "Invalid segment");
+/** Existing workspace/session identifiers are nonempty independent segments. */
+const IdentitySchema = SegmentSchema;
+/** Canonical lower-case Gateway UUID. */
+const GatewayIdSchema = z.string().regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+/** Stable root/file IDs retain the full lowercase SHA-256 digest. */
+const DigestSchema = z.string().regex(/^[0-9a-f]{64}$/);
+/** A literal relative path; the root has an empty path. */
+const PathSchema = z.string().max(4096).refine((value) => value === "" || value.split("/").every((segment) => SegmentSchema.safeParse(segment).success), "Invalid relative path");
+/** Explicit workspace root selection; never defaults to a current chat or home. */
+const FileTargetSchema = z.object({
+	workspaceId: IdentitySchema,
+	rootId: DigestSchema,
+	path: PathSchema
+}).strict();
+/** Root discovery always names an existing workspace. */
+const RootsParamsSchema = z.object({ workspaceId: IdentitySchema }).strict();
+/** Stat always names one explicit current root-relative selection. */
+const StatParamsSchema = z.object({ target: FileTargetSchema }).strict();
+/** Display metadata for one current filesystem object. */
+const FileEntrySchema = z.object({
+	name: z.string(),
+	path: PathSchema,
+	kind: z.enum([
+		"file",
+		"directory",
+		"symlink",
+		"other"
+	]),
+	size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+	modifiedAt: z.number().finite(),
+	fingerprint: DigestSchema,
+	uri: z.string(),
+	referenceKind: z.literal("current"),
+	mutable: z.boolean()
+}).strict();
+/** Validated bounded business context; no arbitrary error object crosses the wire. */
+const ErrorDetailsSchema = z.object({
+	existing: FileEntrySchema.optional(),
+	destinationCommitted: z.boolean().optional(),
+	sourceRetained: z.boolean().optional(),
+	retainedPaths: z.array(PathSchema).max(1e4).optional(),
+	contentLength: z.number().int().nonnegative().optional(),
+	operationId: z.uuid().optional()
+}).strict();
+/** Safe business error result. */
+const AccessErrorSchema = z.object({
+	code: z.string().max(64),
+	message: z.string().max(256),
+	details: ErrorDetailsSchema.optional()
+}).strict();
+/** A retained execution fact or an explicit unknown query result. */
+const OperationResultSchema = z.object({
+	operationId: z.uuid(),
+	instanceId: GatewayIdSchema,
+	status: z.enum([
+		"pending",
+		"succeeded",
+		"failed",
+		"unknown"
+	]),
+	entry: FileEntrySchema.optional(),
+	error: AccessErrorSchema.optional()
+}).strict();
+/** Untrusted upload source metadata, not an authorization or server fingerprint. */
+const FileSourceObservationSchema = z.object({
+	clientName: SegmentSchema,
+	size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+	modifiedAt: z.number().min(-864e13).max(864e13)
+}).strict();
+/** File resource business parameters; PUT additionally requires operationId and source. */
+const FileBytesParamsSchema = z.object({
+	target: FileTargetSchema,
+	expectedFingerprint: DigestSchema.optional(),
+	operationId: z.uuid().optional(),
+	source: FileSourceObservationSchema.optional(),
+	replace: z.boolean().optional(),
+	targetFingerprint: DigestSchema.optional()
+}).strict();
+/** List RPC selection and opaque next-page cursor. */
+const ListParamsSchema = z.object({
+	target: FileTargetSchema,
+	cursor: z.string().max(128).optional()
+}).strict();
+/** One immutable listing generation, with current external-change diagnostics. */
+const ListResultSchema = z.object({
+	entries: z.array(FileEntrySchema).max(200),
+	nextCursor: z.string().optional(),
+	fingerprint: DigestSchema,
+	listingId: z.uuid(),
+	snapshotAt: z.number(),
+	stale: z.boolean()
+}).strict();
+/** Public root display projection. */
+const RootsResultSchema = z.object({ roots: z.array(z.object({
+	id: DigestSchema,
+	kind: z.enum(["own", "directory"]),
+	name: z.string(),
+	path: z.string()
+}).strict()) }).strict();
+/** A complete current-file observation and confirmed host display path. */
+const StatResultSchema = z.object({
+	entry: FileEntrySchema,
+	realPath: z.string()
+}).strict();
+/** Explicit exclusive creation. */
+const MkdirParamsSchema = z.object({
+	target: FileTargetSchema,
+	operationId: z.uuid()
+}).strict();
+/** Same-root rename with optional observed replacement. */
+const RenameParamsSchema = z.object({
+	source: FileTargetSchema,
+	name: SegmentSchema,
+	sourceFingerprint: DigestSchema,
+	operationId: z.uuid(),
+	replace: z.boolean().optional(),
+	targetFingerprint: DigestSchema.optional()
+}).strict();
+/** Same-workspace move to an explicit final target path. */
+const MoveParamsSchema = z.object({
+	source: FileTargetSchema,
+	destination: FileTargetSchema,
+	sourceFingerprint: DigestSchema,
+	operationId: z.uuid(),
+	replace: z.boolean().optional(),
+	targetFingerprint: DigestSchema.optional()
+}).strict();
+/** Removal requires the selected revision and an explicit recursive choice. */
+const RemoveParamsSchema = z.object({
+	target: FileTargetSchema,
+	fingerprint: DigestSchema,
+	recursive: z.boolean(),
+	operationId: z.uuid()
+}).strict();
+/** Query retained facts without executing an operation. */
+const OperationStatusParamsSchema = z.object({
+	instanceId: GatewayIdSchema,
+	operationId: z.uuid()
+}).strict();
+const encoded = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
+const budget = {
+	maxItemBytes: z.number().int().min(1).max(8388608).default(262144),
+	maxTotalBytes: z.number().int().min(1).max(8388608).default(8388608)
+};
+/** Rejects input and declared normalized response costs before any filesystem work. */
+function admit(input, targets, memberBytes, totalBytes, ctx) {
+	if (encoded(input) * 2 > 8388608 || targets.length * memberBytes + 8192 > totalBytes || targets.some((target) => encoded(target) + 4096 > memberBytes)) ctx.addIssue({
+		code: "custom",
+		message: "File collection exceeds its byte budget"
+	});
+}
+/** Complete file observations with independent encoded response budgets. */
+const StatsParamsSchema = z.object({
+	targets: z.array(FileTargetSchema).min(1).max(64),
+	...budget
+}).strict().superRefine((p, ctx) => admit(p, p.targets, p.maxItemBytes, p.maxTotalBytes, ctx));
+/** Retained operation queries never execute work, including unknown identities. */
+const OperationStatusesParamsSchema = z.object({
+	instanceId: GatewayIdSchema,
+	operationIds: z.array(z.uuid()).min(1).max(64),
+	...budget
+}).strict().superRefine((p, ctx) => admit(p, p.operationIds, p.maxItemBytes, p.maxTotalBytes, ctx));
+/** Validates complete mutation members and refuses conflicting reuse before any member starts. */
+function mutations(schema) {
+	return z.object({ items: z.array(schema).min(1).max(64) }).strict().superRefine((p, ctx) => {
+		if (encoded(p) * 2 > 8388608) ctx.addIssue({
+			code: "custom",
+			message: "File collection exceeds its byte budget"
+		});
+		const identities = /* @__PURE__ */ new Map();
+		for (const member of p.items) {
+			const input = JSON.stringify(member);
+			if (identities.has(member.operationId) && identities.get(member.operationId) !== input) ctx.addIssue({
+				code: "custom",
+				message: "Operation identity has conflicting members"
+			});
+			identities.set(member.operationId, input);
+		}
+	});
+}
+/** Each move retains its own complete operation identity and physical outcome. */
+const MoveFilesParamsSchema = mutations(MoveParamsSchema);
+/** Each removal retains its own selected fingerprint and recursive decision. */
+const RemoveFilesParamsSchema = mutations(RemoveParamsSchema);
+/** One notification lists all workspaces physically changed by this collection. */
+const FilesChangedSchema = z.object({ workspaces: z.array(IdentitySchema).min(1).max(64) }).strict();
+/** Complete successful members and bounded safe refusals retain their original order. */
+function collectionResult(target, value) {
+	return z.object({ results: z.array(z.discriminatedUnion("ok", [z.object({
+		index: z.number().int().min(0).max(63),
+		target,
+		ok: z.literal(true),
+		value
+	}).strict(), z.object({
+		index: z.number().int().min(0).max(63),
+		target,
+		ok: z.literal(false),
+		error: AccessErrorSchema
+	}).strict()])).min(1).max(64) }).strict();
+}
+/** Ordered explicit file observations. */
+const StatsResultSchema = collectionResult(FileTargetSchema, StatResultSchema);
+/** Ordered retained operation facts. */
+const OperationStatusesResultSchema = collectionResult(z.uuid(), OperationResultSchema);
+/** Ordered move results keep complete immutable operation members as their safe target. */
+const MoveFilesResultSchema = collectionResult(MoveParamsSchema, OperationResultSchema);
+/** Ordered removal results keep complete immutable operation members as their safe target. */
+const RemoveFilesResultSchema = collectionResult(RemoveParamsSchema, OperationResultSchema);
+//#endregion
+export { AccessErrorSchema, DigestSchema, ErrorDetailsSchema, FileBytesParamsSchema, FileEntrySchema, FileSourceObservationSchema, FileTargetSchema, FilesChangedSchema, GatewayIdSchema, IdentitySchema, ListParamsSchema, ListResultSchema, MkdirParamsSchema, MoveFilesParamsSchema, MoveFilesResultSchema, MoveParamsSchema, OperationResultSchema, OperationStatusParamsSchema, OperationStatusesParamsSchema, OperationStatusesResultSchema, PathSchema, RemoveFilesParamsSchema, RemoveFilesResultSchema, RemoveParamsSchema, RenameParamsSchema, RootsParamsSchema, RootsResultSchema, SegmentSchema, StatParamsSchema, StatResultSchema, StatsParamsSchema, StatsResultSchema, collectionResult };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@eum-agent/file-explorer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "displayName": {
+    "en-US": "Workspace Files",
+    "zh-CN": "工作空间文件"
+  },
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Sessionless workspace file browsing, transfers and private references",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "default": "./dist/schema.js"
+    }
+  },
+  "files": [
+    "dist",
+    "ui"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eum-agent/plugin": "1.0.1",
+    "@eum-agent/protocol": "1.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "vite": "^8.2.2",
+    "@eum-agent/infra-local": "1.0.1"
+  },
+  "yaoguang": {
+    "description": {
+      "en-US": "Sessionless workspace file browsing, transfers and private references",
+      "zh-CN": "独立的工作区文件浏览、传输与私有引用"
+    },
+    "dependencies": {
+      "@eum-agent/file-references": "1.0.1"
+    },
+    "kind": "extension",
+    "foundationDependencies": {
+      "@eum-agent/infra-local": "1.0.1"
+    }
+  },
+  "scripts": {
+    "build": "tsdown && vite build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.ui.json"
+  }
 }