@blu1606/create-walrus-app 0.1.0

package/dist/test-base.js

@@ -0,0 +1,42 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const basePath = path.join(__dirname, '../../../templates/base');
+const requiredFiles = [
+    'src/adapters/storage.ts',
+    'src/types/walrus.ts',
+    'src/types/index.ts',
+    'src/utils/env.ts',
+    'src/utils/format.ts',
+    '.env.example',
+    '.gitignore',
+    'package.json',
+    'tsconfig.json',
+    'README.md',
+];
+let passed = 0;
+let failed = 0;
+console.log('🔍 Validating base template structure...\n');
+for (const file of requiredFiles) {
+    const fullPath = path.join(basePath, file);
+    const exists = fs.existsSync(fullPath);
+    if (exists) {
+        console.log(`✓ ${file}`);
+        passed++;
+    }
+    else {
+        console.log(`✗ MISSING: ${file}`);
+        failed++;
+    }
+}
+console.log(`\n${passed}/${requiredFiles.length} files found`);
+if (failed > 0) {
+    console.error(`\n❌ Validation failed: ${failed} files missing`);
+    process.exit(1);
+}
+else {
+    console.log('\n✅ Base layer validation passed!');
+    process.exit(0);
+}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export type SDK = 'mysten' | 'tusky' | 'hibernuts';
+export type Framework = 'react' | 'vue' | 'plain-ts';
+export type UseCase = 'simple-upload' | 'gallery' | 'defi-nft';
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+export interface Context {
+    projectName: string;
+    projectPath: string;
+    sdk: SDK;
+    framework: Framework;
+    useCase: UseCase;
+    analytics: boolean;
+    tailwind: boolean;
+    packageManager: PackageManager;
+}
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    suggestion?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+describe('Type definitions', () => {
+    it('should allow valid SDK values', () => {
+        const sdks = ['mysten', 'tusky', 'hibernuts'];
+        expect(sdks).toHaveLength(3);
+    });
+    it('should allow valid Framework values', () => {
+        const frameworks = ['react', 'vue', 'plain-ts'];
+        expect(frameworks).toHaveLength(3);
+    });
+    it('should allow valid UseCase values', () => {
+        const useCases = ['simple-upload', 'gallery', 'defi-nft'];
+        expect(useCases).toHaveLength(3);
+    });
+    it('should allow valid PackageManager values', () => {
+        const pms = ['npm', 'pnpm', 'yarn', 'bun'];
+        expect(pms).toHaveLength(4);
+    });
+    it('should create valid Context object', () => {
+        const context = {
+            projectName: 'test-app',
+            projectPath: '/path/to/test-app',
+            sdk: 'mysten',
+            framework: 'react',
+            useCase: 'simple-upload',
+            analytics: false,
+            tailwind: true,
+            packageManager: 'pnpm',
+        };
+        expect(context.projectName).toBe('test-app');
+        expect(context.sdk).toBe('mysten');
+        expect(context.framework).toBe('react');
+        expect(context.useCase).toBe('simple-upload');
+        expect(context.analytics).toBe(false);
+        expect(context.tailwind).toBe(true);
+        expect(context.packageManager).toBe('pnpm');
+    });
+    it('should create valid ValidationResult with success', () => {
+        const result = {
+            valid: true,
+        };
+        expect(result.valid).toBe(true);
+        expect(result.error).toBeUndefined();
+        expect(result.suggestion).toBeUndefined();
+    });
+    it('should create valid ValidationResult with error', () => {
+        const result = {
+            valid: false,
+            error: 'Something went wrong',
+            suggestion: 'Try this instead',
+        };
+        expect(result.valid).toBe(false);
+        expect(result.error).toBe('Something went wrong');
+        expect(result.suggestion).toBe('Try this instead');
+    });
+    it('should allow ValidationResult with error but no suggestion', () => {
+        const result = {
+            valid: false,
+            error: 'Error without suggestion',
+        };
+        expect(result.valid).toBe(false);
+        expect(result.error).toBe('Error without suggestion');
+        expect(result.suggestion).toBeUndefined();
+    });
+});

package/dist/utils/detect-pm.d.ts

@@ -0,0 +1,2 @@
+import { PackageManager } from '../types.js';
+export declare function detectPackageManager(): PackageManager;

package/dist/utils/detect-pm.js

@@ -0,0 +1,10 @@
+export function detectPackageManager() {
+    const userAgent = process.env.npm_config_user_agent;
+    if (userAgent?.includes('pnpm'))
+        return 'pnpm';
+    if (userAgent?.includes('yarn'))
+        return 'yarn';
+    if (userAgent?.includes('bun'))
+        return 'bun';
+    return 'npm';
+}

package/dist/utils/detect-pm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/detect-pm.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { detectPackageManager } from './detect-pm.js';
+describe('detectPackageManager', () => {
+    let originalUserAgent;
+    beforeEach(() => {
+        originalUserAgent = process.env.npm_config_user_agent;
+    });
+    afterEach(() => {
+        if (originalUserAgent === undefined) {
+            delete process.env.npm_config_user_agent;
+        }
+        else {
+            process.env.npm_config_user_agent = originalUserAgent;
+        }
+    });
+    it('should detect pnpm from user agent', () => {
+        process.env.npm_config_user_agent = 'pnpm/8.6.0 npm/? node/v18.16.0 linux x64';
+        expect(detectPackageManager()).toBe('pnpm');
+    });
+    it('should detect yarn from user agent', () => {
+        process.env.npm_config_user_agent = 'yarn/1.22.19 npm/? node/v18.16.0 linux x64';
+        expect(detectPackageManager()).toBe('yarn');
+    });
+    it('should detect bun from user agent', () => {
+        process.env.npm_config_user_agent = 'bun/1.0.0';
+        expect(detectPackageManager()).toBe('bun');
+    });
+    it('should default to npm when no user agent', () => {
+        delete process.env.npm_config_user_agent;
+        expect(detectPackageManager()).toBe('npm');
+    });
+    it('should default to npm for unknown user agent', () => {
+        process.env.npm_config_user_agent = 'unknown/1.0.0';
+        expect(detectPackageManager()).toBe('npm');
+    });
+    it('should handle user agent with pnpm in different positions', () => {
+        process.env.npm_config_user_agent = 'npm/? pnpm/8.0.0 node/v18.0.0';
+        expect(detectPackageManager()).toBe('pnpm');
+    });
+    it('should prioritize pnpm over yarn when both present', () => {
+        process.env.npm_config_user_agent = 'pnpm/8.0.0 yarn/1.22.0';
+        expect(detectPackageManager()).toBe('pnpm');
+    });
+    it('should prioritize yarn over bun when both present', () => {
+        process.env.npm_config_user_agent = 'yarn/1.22.0 bun/1.0.0';
+        expect(detectPackageManager()).toBe('yarn');
+    });
+    it('should handle empty string user agent', () => {
+        process.env.npm_config_user_agent = '';
+        expect(detectPackageManager()).toBe('npm');
+    });
+});

package/dist/utils/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const logger: {
+    info: (msg: string) => void;
+    success: (msg: string) => void;
+    error: (msg: string) => void;
+    warn: (msg: string) => void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,7 @@
+import kleur from 'kleur';
+export const logger = {
+    info: (msg) => console.log(kleur.blue('ℹ'), msg),
+    success: (msg) => console.log(kleur.green('✓'), msg),
+    error: (msg) => console.error(kleur.red('✗'), msg),
+    warn: (msg) => console.warn(kleur.yellow('⚠'), msg),
+};

package/dist/validator.d.ts

@@ -0,0 +1,3 @@
+import { Context, ValidationResult } from './types.js';
+export declare function validateContext(context: Context): ValidationResult;
+export declare function validateProjectName(name: string): boolean | string;

package/dist/validator.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { COMPATIBILITY_MATRIX } from './matrix.js';
+export function validateContext(context) {
+    const { sdk, framework, useCase } = context;
+    // Check framework compatibility
+    if (!COMPATIBILITY_MATRIX[sdk].frameworks.includes(framework)) {
+        return {
+            valid: false,
+            error: `SDK "${sdk}" is incompatible with framework "${framework}"`,
+            suggestion: `Compatible frameworks for ${sdk}: ${COMPATIBILITY_MATRIX[sdk].frameworks.join(', ')}`,
+        };
+    }
+    // Check use case compatibility
+    if (!COMPATIBILITY_MATRIX[sdk].useCases.includes(useCase)) {
+        return {
+            valid: false,
+            error: `SDK "${sdk}" does not support use case "${useCase}"`,
+            suggestion: `Supported use cases for ${sdk}: ${COMPATIBILITY_MATRIX[sdk].useCases.join(', ')}`,
+        };
+    }
+    return { valid: true };
+}
+export function validateProjectName(name) {
+    // Check for empty string
+    if (!name || name.trim().length === 0) {
+        return 'Project name cannot be empty';
+    }
+    // npm package name length limit (214 characters)
+    if (name.length > 214) {
+        return 'Project name must be 214 characters or less';
+    }
+    // Prevent path traversal
+    if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+        return 'Project name cannot contain path separators';
+    }
+    // Prevent absolute paths
+    if (path.isAbsolute(name)) {
+        return 'Project name cannot be an absolute path';
+    }
+    // npm package naming rules
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        return 'Project name must contain only lowercase letters, numbers, and hyphens';
+    }
+    if (name.startsWith('-') || name.endsWith('-')) {
+        return 'Project name cannot start or end with a hyphen';
+    }
+    return true;
+}

package/dist/validator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/validator.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { validateProjectName, validateContext } from './validator.js';
+describe('validateProjectName', () => {
+    it('should accept valid project names', () => {
+        expect(validateProjectName('my-project')).toBe(true);
+        expect(validateProjectName('app123')).toBe(true);
+        expect(validateProjectName('walrus-app-v2')).toBe(true);
+    });
+    it('should reject names with path traversal', () => {
+        expect(validateProjectName('../my-project')).toContain('path separators');
+        expect(validateProjectName('../../escape')).toContain('path separators');
+        expect(validateProjectName('test/../bad')).toContain('path separators');
+    });
+    it('should reject names with forward slashes', () => {
+        expect(validateProjectName('my/project')).toContain('path separators');
+        expect(validateProjectName('/absolute/path')).toContain('path separators');
+    });
+    it('should reject names with backslashes', () => {
+        expect(validateProjectName('my\\project')).toContain('path separators');
+        expect(validateProjectName('C:\\Windows\\path')).toContain('path separators');
+    });
+    it('should reject absolute paths', () => {
+        expect(validateProjectName('/usr/local/bin')).toContain('path');
+        expect(validateProjectName('C:\\Program Files')).toContain('path');
+    });
+    it('should reject names with uppercase letters', () => {
+        expect(validateProjectName('MyProject')).toContain('lowercase');
+        expect(validateProjectName('TEST')).toContain('lowercase');
+    });
+    it('should reject names with special characters', () => {
+        expect(validateProjectName('my_project')).toContain('lowercase');
+        expect(validateProjectName('my.project')).toContain('lowercase');
+        expect(validateProjectName('my@project')).toContain('lowercase');
+        expect(validateProjectName('my project')).toContain('lowercase');
+    });
+    it('should reject names starting with hyphen', () => {
+        expect(validateProjectName('-myproject')).toContain('hyphen');
+    });
+    it('should reject names ending with hyphen', () => {
+        expect(validateProjectName('myproject-')).toContain('hyphen');
+    });
+    it('should accept names with hyphens in middle', () => {
+        expect(validateProjectName('my-awesome-project')).toBe(true);
+    });
+    it('should accept numbers in names', () => {
+        expect(validateProjectName('app123')).toBe(true);
+        expect(validateProjectName('2024-project')).toBe(true);
+    });
+});
+describe('validateContext', () => {
+    const createContext = (overrides = {}) => ({
+        projectName: 'test-app',
+        projectPath: '/path/to/test-app',
+        sdk: 'mysten',
+        framework: 'react',
+        useCase: 'simple-upload',
+        analytics: false,
+        tailwind: true,
+        packageManager: 'pnpm',
+        ...overrides,
+    });
+    it('should validate compatible sdk and framework combinations', () => {
+        expect(validateContext(createContext({ sdk: 'mysten', framework: 'react' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'mysten', framework: 'vue' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'mysten', framework: 'plain-ts' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'tusky', framework: 'react' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'hibernuts', framework: 'react' }))).toEqual({ valid: true });
+    });
+    it('should reject incompatible sdk and framework combinations', () => {
+        const result = validateContext(createContext({ sdk: 'hibernuts', framework: 'vue' }));
+        expect(result.valid).toBe(false);
+        expect(result.error).toContain('incompatible');
+        expect(result.suggestion).toContain('Compatible frameworks');
+    });
+    it('should validate compatible sdk and useCase combinations', () => {
+        expect(validateContext(createContext({ sdk: 'mysten', useCase: 'simple-upload' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'mysten', useCase: 'gallery' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'mysten', useCase: 'defi-nft' }))).toEqual({ valid: true });
+        expect(validateContext(createContext({ sdk: 'tusky', useCase: 'simple-upload' }))).toEqual({ valid: true });
+    });
+    it('should reject incompatible sdk and useCase combinations', () => {
+        const result = validateContext(createContext({ sdk: 'tusky', useCase: 'defi-nft' }));
+        expect(result.valid).toBe(false);
+        expect(result.error).toContain('does not support');
+        expect(result.suggestion).toContain('Supported use cases');
+    });
+    it('should reject hibernuts with gallery use case', () => {
+        const result = validateContext(createContext({ sdk: 'hibernuts', useCase: 'gallery' }));
+        expect(result.valid).toBe(false);
+        expect(result.error).toBeDefined();
+    });
+    it('should provide helpful suggestions in error messages', () => {
+        const result = validateContext(createContext({ sdk: 'hibernuts', framework: 'vue' }));
+        expect(result.suggestion).toMatch(/react|plain-ts/);
+    });
+});

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@blu1606/create-walrus-app",
+  "version": "0.1.0",
+  "description": "Interactive CLI for scaffolding Walrus applications",
+  "type": "module",
+  "bin": {
+    "create-walrus-app": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "node tests/integration/integration.test.mjs",
+    "test:validation": "node tests/integration/validation.test.mjs",
+    "test:manual": "node tests/integration/manual.test.js",
+    "test:e2e": "node tests/integration/cli.e2e.test.mjs",
+    "test:all": "vitest run && pnpm test:e2e",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "walrus",
+    "sui",
+    "scaffold",
+    "cli",
+    "template"
+  ],
+  "author": "blu1606 dongthanhquandtq@gmail.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blu1606/walrus-starter-kit.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "cross-spawn": "^7.0.3",
+    "fs-extra": "^11.2.0",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2",
+    "sort-package-json": "^2.10.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.11.0",
+    "@types/prompts": "^2.4.9",
+    "@vitest/coverage-v8": "^4.0.17",
+    "@vitest/ui": "^4.0.17",
+    "execa": "^9.5.2",
+    "strip-ansi": "^7.1.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/base/.env.example

@@ -0,0 +1,31 @@
+## ==============================================
+## Walrus Application - Environment Configuration
+## ==============================================
+
+## WALRUS NETWORK SETTINGS
+## Network: testnet | mainnet | devnet
+VITE_WALRUS_NETWORK=testnet
+
+## Walrus Aggregator URL (for downloads)
+VITE_WALRUS_AGGREGATOR=https://aggregator.walrus-testnet.walrus.space
+
+## Walrus Publisher URL (for uploads)
+VITE_WALRUS_PUBLISHER=https://publisher.walrus-testnet.walrus.space
+
+## SUI BLOCKCHAIN SETTINGS
+## Sui Network: testnet | mainnet | devnet
+VITE_SUI_NETWORK=testnet
+
+## Sui RPC URL (for wallet interactions)
+VITE_SUI_RPC=https://fullnode.testnet.sui.io:443
+
+## OPTIONAL FEATURES
+## Blockberry Analytics API Key (leave empty to disable)
+VITE_BLOCKBERRY_KEY=
+
+## ==============================================
+## PREREQUISITES
+## ==============================================
+## 1. Install Sui Wallet browser extension
+## 2. Get testnet SUI from faucet: https://faucet.testnet.sui.io/
+## 3. Copy this file to .env and fill in any optional values

package/templates/base/README.md

@@ -0,0 +1,54 @@
+# {{projectName}}
+
+This is a Walrus application generated by `create-walrus-app`.
+
+## What's Included
+
+### Adapter Interface
+
+- `src/adapters/storage.ts` - Universal SDK-agnostic interface
+- Allows use case code to work with any Walrus SDK
+
+### Type Definitions
+
+- `src/types/walrus.ts` - Walrus-specific types
+- `src/types/index.ts` - Common utility types
+
+### Utilities
+
+- `src/utils/env.ts` - Environment validation
+- `src/utils/format.ts` - Formatting helpers
+
+### Configuration
+
+- `.env.example` - Environment template
+- `tsconfig.json` - TypeScript strict mode config
+- `package.json` - Base dependencies
+
+## Layer Composition
+
+This base layer is **always included** and combined with:
+
+1. **SDK Layer** (e.g., `sdk-mysten/`) - Implements `StorageAdapter`
+2. **Framework Layer** (e.g., `react/`) - UI framework setup
+3. **Use Case Layer** (e.g., `simple-upload/`) - Application logic
+
+```
+Base + SDK + Framework + UseCase = Your App
+```
+
+## Environment Setup
+
+1. Copy `.env.example` to `.env`
+2. Fill in required values:
+   - Walrus network URLs
+   - Sui RPC endpoint
+3. Optional: Add Blockberry API key
+
+## Next Steps
+
+This base layer is completed by:
+
+- **Phase 4**: SDK implementation
+- **Phase 5**: Framework setup
+- **Phase 6**: Use case logic

package/templates/base/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "echo 'Override by framework layer'",
+    "build": "echo 'Override by framework layer'",
+    "preview": "echo 'Override by framework layer'",
+    "lint": "eslint . --ext .ts,.tsx",
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "eslint": "^8.56.0",
+    "@typescript-eslint/parser": "^6.19.1",
+    "@typescript-eslint/eslint-plugin": "^6.19.1"
+  }
+}

package/templates/base/src/adapters/storage.ts

@@ -0,0 +1,58 @@
+/**
+ * Universal storage adapter interface for Walrus
+ *
+ * This interface abstracts SDK-specific implementations,
+ * allowing use case layers to work with any Walrus SDK.
+ */
+
+export interface BlobMetadata {
+  blobId: string;
+  size: number;
+  contentType?: string;
+  createdAt: number;
+  expiresAt?: number;
+}
+
+export interface UploadOptions {
+  /** Number of epochs to store (Walrus-specific) */
+  epochs?: number;
+  /** MIME type of the content */
+  contentType?: string;
+}
+
+export interface DownloadOptions {
+  /** Byte range (for large files) */
+  range?: { start: number; end: number };
+}
+
+export interface StorageAdapter {
+  /**
+   * Upload data to Walrus storage
+   * @param data - File or raw bytes to upload
+   * @param options - Upload configuration
+   * @returns Blob ID (permanent reference)
+   */
+  upload(data: File | Uint8Array, options?: UploadOptions): Promise<string>;
+
+  /**
+   * Download blob data by ID
+   * @param blobId - Unique blob identifier
+   * @param options - Download configuration
+   * @returns Raw blob data
+   */
+  download(blobId: string, options?: DownloadOptions): Promise<Uint8Array>;
+
+  /**
+   * Get blob metadata without downloading content
+   * @param blobId - Unique blob identifier
+   * @returns Metadata object
+   */
+  getMetadata(blobId: string): Promise<BlobMetadata>;
+
+  /**
+   * Check if blob exists
+   * @param blobId - Unique blob identifier
+   * @returns True if blob is accessible
+   */
+  exists(blobId: string): Promise<boolean>;
+}

package/templates/base/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from './walrus.js';
+
+export interface Result<T, E = Error> {
+  success: boolean;
+  data?: T;
+  error?: E;
+}
+
+export type AsyncResult<T, E = Error> = Promise<Result<T, E>>;

package/templates/base/src/types/walrus.ts

@@ -0,0 +1,22 @@
+export type WalrusNetwork = 'testnet' | 'mainnet' | 'devnet';
+
+export interface WalrusConfig {
+  network: WalrusNetwork;
+  publisherUrl: string;
+  aggregatorUrl: string;
+  suiRpcUrl: string;
+}
+
+export interface BlobInfo {
+  blobId: string;
+  name?: string;
+  size: number;
+  contentType?: string;
+  uploadedAt: number;
+}
+
+export interface StorageStats {
+  totalBlobs: number;
+  totalSize: number;
+  usedEpochs: number;
+}