@kb-labs/workflow-artifacts 1.1.0

package/README.md

@@ -0,0 +1,214 @@
+# @kb-labs/workflow-artifacts
+
+Artifact helpers for KB Labs workflow engine.
+
+## Vision & Purpose
+
+**@kb-labs/workflow-artifacts** provides artifact helpers for the KB Labs workflow engine. It includes file system client for reading and writing workflow artifacts, artifact management, and path organization.
+
+### Core Goals
+
+- **File System Client**: Operations for reading and writing workflow artifacts
+- **Artifact Management**: Helpers for artifact paths and organization
+- **Stream Support**: Support for streaming artifacts
+
+## Package Status
+
+- **Version**: 0.1.0
+- **Stage**: Stable
+- **Status**: Production Ready ✅
+
+## Architecture
+
+### High-Level Overview
+
+```
+Workflow Artifacts
+    │
+    ├──► File System Client
+    ├──► Artifact Types
+    └──► Path Management
+```
+
+### Key Components
+
+1. **FileSystemArtifactClient** (`fs-client.ts`): File system-based artifact client
+2. **Types** (`types.ts`): Artifact type definitions
+
+## ✨ Features
+
+- **File system client** for artifacts
+- **Read/write operations** for artifacts
+- **Stream support** for large artifacts
+- **Path validation** and security
+- **List operations** for artifact discovery
+
+## 📦 API Reference
+
+### Main Exports
+
+#### Client Classes
+
+- `FileSystemArtifactClient`: File system-based artifact client
+- `createFileSystemArtifactClient(options)`: Factory function
+
+#### Types & Interfaces
+
+- `ArtifactClient`: Artifact client interface
+- `ArtifactInput`: Artifact input types
+- `ArtifactOutput`: Artifact output type
+- `ArtifactReference`: Artifact reference type
+
+### Types & Interfaces
+
+#### `ArtifactClient`
+
+```typescript
+interface ArtifactClient {
+  produce(path: string, input: ArtifactInput): Promise<void>;
+  consume(path: string): Promise<ArtifactOutput>;
+  list?(prefix?: string): Promise<ArtifactReference[]>;
+  basePath?: () => string;
+}
+```
+
+#### `ArtifactInput`
+
+```typescript
+type ArtifactInput =
+  | string
+  | Buffer
+  | Uint8Array
+  | NodeJS.ReadableStream;
+```
+
+#### `ArtifactReference`
+
+```typescript
+interface ArtifactReference {
+  path: string;
+  size?: number;
+  contentType?: string;
+  modifiedAt?: Date;
+}
+```
+
+## 🔧 Configuration
+
+### Configuration Options
+
+#### FileSystemArtifactClientOptions
+
+- **root**: Root directory for artifacts (required)
+- **defaultContentType**: Default content type
+
+## 🔗 Dependencies
+
+### Runtime Dependencies
+
+- `pathe` (`^1.1.2`): Path utilities
+
+### Development Dependencies
+
+- `@kb-labs/devkit` (`link:../../../kb-labs-devkit`): DevKit presets
+- `@types/node` (`^24.3.3`): Node.js types
+- `tsup` (`^8.5.0`): TypeScript bundler
+- `typescript` (`^5.6.3`): TypeScript compiler
+- `vitest` (`^3.2.4`): Test runner
+
+## 🧪 Testing
+
+### Test Structure
+
+```
+src/__tests__/
+└── (tests to be added)
+```
+
+### Test Coverage
+
+- **Current Coverage**: ~0% (tests to be added)
+- **Target Coverage**: 90%
+
+## 📈 Performance
+
+### Performance Characteristics
+
+- **Time Complexity**: O(1) for operations, O(n) for listing
+- **Space Complexity**: O(1)
+- **Bottlenecks**: File I/O operations
+
+## 🔒 Security
+
+### Security Considerations
+
+- **Path Validation**: Path escaping prevention
+- **Root Directory**: Artifacts restricted to root directory
+
+### Known Vulnerabilities
+
+- None
+
+## 🐛 Known Issues & Limitations
+
+### Known Issues
+
+- None currently
+
+### Limitations
+
+- **File System Only**: Only file system implementation
+- **No Remote Storage**: No S3/remote storage support
+
+### Future Improvements
+
+- **Remote Storage**: S3/remote storage support
+- **Compression**: Artifact compression support
+
+## 🔄 Migration & Breaking Changes
+
+### Migration from Previous Versions
+
+No breaking changes in current version (0.1.0).
+
+### Breaking Changes in Future Versions
+
+- None planned
+
+## 📚 Examples
+
+### Example 1: Create Artifact Client
+
+```typescript
+import { createFileSystemArtifactClient } from '@kb-labs/workflow-artifacts';
+
+const client = createFileSystemArtifactClient({
+  root: '/path/to/artifacts',
+});
+```
+
+### Example 2: Read Artifact
+
+```typescript
+const content = await client.consume('run-123/job-abc/artifact.txt');
+```
+
+### Example 3: Write Artifact
+
+```typescript
+await client.produce('run-123/job-abc/artifact.txt', 'content');
+```
+
+### Example 4: List Artifacts
+
+```typescript
+const artifacts = await client.list('run-123/');
+```
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+MIT © KB Labs

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+type ArtifactInput = string | Buffer | Uint8Array | NodeJS.ReadableStream;
+type ArtifactOutput = Buffer;
+interface ArtifactReference {
+    path: string;
+    size?: number;
+    contentType?: string;
+    modifiedAt?: Date;
+}
+interface ArtifactClient {
+    produce(path: string, input: ArtifactInput): Promise<void>;
+    consume(path: string): Promise<ArtifactOutput>;
+    list?(prefix?: string): Promise<ArtifactReference[]>;
+    basePath?: () => string;
+}
+
+interface FileSystemArtifactClientOptions {
+    root: string;
+    defaultContentType?: string;
+}
+declare class FileSystemArtifactClient implements ArtifactClient {
+    private readonly options;
+    constructor(options: FileSystemArtifactClientOptions);
+    basePath(): string;
+    produce(path: string, input: ArtifactInput): Promise<void>;
+    consume(path: string): Promise<ArtifactOutput>;
+    stream(path: string): Promise<NodeJS.ReadableStream>;
+    list(prefix?: string): Promise<ArtifactReference[]>;
+}
+declare function createFileSystemArtifactClient(root: string): FileSystemArtifactClient;
+
+export { type ArtifactClient, type ArtifactInput, type ArtifactOutput, type ArtifactReference, FileSystemArtifactClient, type FileSystemArtifactClientOptions, createFileSystemArtifactClient };

package/dist/index.js

@@ -0,0 +1,84 @@
+import { createReadStream, createWriteStream } from 'fs';
+import { readFile, writeFile, readdir, stat, mkdir } from 'fs/promises';
+import { pipeline } from 'stream/promises';
+import { resolve, join, relative, dirname } from 'pathe';
+
+// src/fs-client.ts
+function ensureWithinRoot(root, targetPath) {
+  const normalizedRoot = root.endsWith("/") ? root : `${root}/`;
+  const target = resolve(root, targetPath);
+  if (target === normalizedRoot.slice(0, -1)) {
+    return target;
+  }
+  if (!target.startsWith(normalizedRoot)) {
+    throw new Error(`Artifact path escapes root: ${targetPath}`);
+  }
+  return target;
+}
+async function writeInput(destination, input) {
+  if (typeof input === "string" || input instanceof Buffer || input instanceof Uint8Array) {
+    await createParentDir(destination);
+    await writeFile(destination, input);
+    return;
+  }
+  if (input && typeof input.pipe === "function") {
+    await createParentDir(destination);
+    await pipeline(input, createWriteStream(destination));
+    return;
+  }
+  throw new Error("Unsupported artifact input type");
+}
+async function createParentDir(path) {
+  await mkdir(dirname(path), { recursive: true });
+}
+async function walk(root, prefix) {
+  const base = prefix ? ensureWithinRoot(root, prefix) : root;
+  const entries = await readdir(base, { withFileTypes: true });
+  const entryPromises = entries.map(async (entry) => {
+    const absolute = join(base, entry.name);
+    const rel = relative(root, absolute);
+    if (entry.isDirectory()) {
+      return walk(root, rel);
+    } else if (entry.isFile()) {
+      const s = await stat(absolute);
+      return [{
+        path: rel,
+        size: s.size,
+        modifiedAt: s.mtime
+      }];
+    }
+    return [];
+  });
+  const nestedResults = await Promise.all(entryPromises);
+  return nestedResults.flat();
+}
+var FileSystemArtifactClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  basePath() {
+    return this.options.root;
+  }
+  async produce(path, input) {
+    const target = ensureWithinRoot(this.options.root, path);
+    await writeInput(target, input);
+  }
+  async consume(path) {
+    const target = ensureWithinRoot(this.options.root, path);
+    return readFile(target);
+  }
+  async stream(path) {
+    const target = ensureWithinRoot(this.options.root, path);
+    return createReadStream(target);
+  }
+  async list(prefix) {
+    return walk(this.options.root, prefix);
+  }
+};
+function createFileSystemArtifactClient(root) {
+  return new FileSystemArtifactClient({ root });
+}
+
+export { FileSystemArtifactClient, createFileSystemArtifactClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fs-client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { createWriteStream, createReadStream } from 'node:fs'\nimport { mkdir, stat, readdir, readFile, writeFile } from 'node:fs/promises'\nimport { pipeline } from 'node:stream/promises'\nimport { dirname, resolve, join, relative } from 'pathe'\nimport type {\n  ArtifactClient,\n  ArtifactInput,\n  ArtifactOutput,\n  ArtifactReference,\n} from './types'\n\nfunction ensureWithinRoot(root: string, targetPath: string): string {\n  const normalizedRoot = root.endsWith('/') ? root : `${root}/`\n  const target = resolve(root, targetPath)\n  if (target === normalizedRoot.slice(0, -1)) {\n    return target\n  }\n  if (!target.startsWith(normalizedRoot)) {\n    throw new Error(`Artifact path escapes root: ${targetPath}`)\n  }\n  return target\n}\n\nasync function writeInput(\n  destination: string,\n  input: ArtifactInput,\n): Promise<void> {\n  if (\n    typeof input === 'string' ||\n    input instanceof Buffer ||\n    input instanceof Uint8Array\n  ) {\n    await createParentDir(destination)\n    await writeFile(destination, input)\n    return\n  }\n\n  if (input && typeof input.pipe === 'function') {\n    await createParentDir(destination)\n    await pipeline(input, createWriteStream(destination))\n    return\n  }\n\n  throw new Error('Unsupported artifact input type')\n}\n\nasync function createParentDir(path: string): Promise<void> {\n  await mkdir(dirname(path), { recursive: true })\n}\n\nasync function walk(root: string, prefix?: string): Promise<ArtifactReference[]> {\n  const base = prefix ? ensureWithinRoot(root, prefix) : root\n  const entries = await readdir(base, { withFileTypes: true })\n\n  // Process all entries in parallel\n  const entryPromises = entries.map(async (entry) => {\n    const absolute = join(base, entry.name)\n    const rel = relative(root, absolute)\n\n    if (entry.isDirectory()) {\n      return walk(root, rel)\n    } else if (entry.isFile()) {\n      const s = await stat(absolute)\n      return [{\n        path: rel,\n        size: s.size,\n        modifiedAt: s.mtime,\n      }]\n    }\n    return []\n  })\n\n  const nestedResults = await Promise.all(entryPromises)\n  return nestedResults.flat()\n}\n\nexport interface FileSystemArtifactClientOptions {\n  root: string\n  defaultContentType?: string\n}\n\nexport class FileSystemArtifactClient implements ArtifactClient {\n  constructor(private readonly options: FileSystemArtifactClientOptions) {}\n\n  basePath(): string {\n    return this.options.root\n  }\n\n  async produce(path: string, input: ArtifactInput): Promise<void> {\n    const target = ensureWithinRoot(this.options.root, path)\n    await writeInput(target, input)\n  }\n\n  async consume(path: string): Promise<ArtifactOutput> {\n    const target = ensureWithinRoot(this.options.root, path)\n    return readFile(target)\n  }\n\n  async stream(path: string): Promise<NodeJS.ReadableStream> {\n    const target = ensureWithinRoot(this.options.root, path)\n    return createReadStream(target)\n  }\n\n  async list(prefix?: string): Promise<ArtifactReference[]> {\n    return walk(this.options.root, prefix)\n  }\n}\n\nexport function createFileSystemArtifactClient(\n  root: string,\n): FileSystemArtifactClient {\n  return new FileSystemArtifactClient({ root })\n}\n\n\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kb-labs/workflow-artifacts",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Artifact helpers for KB Labs workflow engine.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm clean && tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint . --ignore-pattern 'dist/**'",
+    "lint:fix": "eslint . --fix --ignore-pattern 'dist/**'",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "pathe": "^1.1.2"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "@typescript-eslint/eslint-plugin": "^8",
+    "@typescript-eslint/parser": "^8",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}