@aspects-ai/workspace-cli 0.1.0

package/README.md

@@ -0,0 +1,268 @@
+# @aspects-ai/workspace-cli
+
+Lightweight CLI for installing libraries into workspaces. Designed to be AI-friendly and CI/CD compatible.
+
+## Features
+
+- Simple, non-interactive commands
+- Git-based library installation via sparse checkout
+- Environment variable authentication only (no prompts)
+- Automatic dependency management
+- Tracks installed libraries in `workspace.config.json`
+
+## Installation
+
+```bash
+npm install -g @aspects-ai/workspace-cli
+```
+
+Or use with npx:
+
+```bash
+npx @aspects-ai/workspace-cli <command>
+```
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- Git installed and available in PATH
+- GitHub personal access token (for private repositories)
+
+## Authentication
+
+Set the `WORKSPACE_CLI_TOKEN` environment variable with your GitHub personal access token:
+
+```bash
+export WORKSPACE_CLI_TOKEN=ghp_xxxxxxxxxxxx
+```
+
+The token needs read access to the repositories containing the libraries.
+
+## Commands
+
+### `init`
+
+Initialize workspace configuration. Creates `workspace.config.json` in the current workspace.
+
+```bash
+workspace-cli init
+```
+
+### `list`
+
+List all available libraries in the registry.
+
+```bash
+workspace-cli list
+```
+
+Example output:
+```
+Available libraries:
+
+  animate-core @0.1.3
+    Core animation components for Noodle videos
+
+Total: 1 library
+```
+
+### `add <library>`
+
+Install a library into the workspace.
+
+```bash
+WORKSPACE_CLI_TOKEN=ghp_xxx workspace-cli add animate-core
+```
+
+Options:
+- `-f, --force` - Force reinstall if already installed
+
+The command will:
+1. Fetch the library from the git repository
+2. Install it to `./core/<library-name>/`
+3. Update `workspace.config.json`
+4. Add dependencies to `package.json`
+
+## Usage Examples
+
+### Basic Workflow
+
+```bash
+# Navigate to your workspace
+cd my-workspace
+
+# Initialize workspace config
+workspace-cli init
+
+# View available libraries
+workspace-cli list
+
+# Install a library (requires token)
+export WORKSPACE_CLI_TOKEN=ghp_xxxxxxxxxxxx
+workspace-cli add animate-core
+
+# Install dependencies
+npm install
+```
+
+### CI/CD Usage
+
+```yaml
+# .github/workflows/setup.yml
+name: Setup Workspace
+
+on: [push]
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install libraries
+        env:
+          WORKSPACE_CLI_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          npx @aspects-ai/workspace-cli add animate-core
+
+      - name: Install dependencies
+        run: npm install
+```
+
+### AI Agent Usage
+
+The CLI is designed to be used by AI agents without any interactive prompts:
+
+```bash
+# All commands fail fast with clear error messages
+# No confirmation prompts
+# Machine-readable output
+
+WORKSPACE_CLI_TOKEN=$TOKEN workspace-cli add animate-core
+```
+
+## Configuration
+
+### workspace.config.json
+
+The CLI creates and manages `workspace.config.json` in your workspace:
+
+```json
+{
+  "version": "1.0",
+  "coreDir": "./core",
+  "libraries": {
+    "animate-core": {
+      "version": "0.1.3",
+      "installedAt": "2025-10-15T12:34:56Z",
+      "commit": "097cf62abc123"
+    }
+  }
+}
+```
+
+### Library Registry
+
+Libraries are defined in `src/registry/libraries.json`:
+
+```json
+{
+  "libraries": {
+    "animate-core": {
+      "name": "@aspects-ai/noodle-animate-core",
+      "description": "Core animation components for Noodle videos",
+      "version": "0.1.3",
+      "repository": {
+        "url": "https://github.com/aspects-ai/noodle-templates.git",
+        "directory": "noodle-animate-core/src",
+        "branch": "main"
+      },
+      "installPath": "animate-core",
+      "dependencies": {
+        "react": "19.1.0",
+        "remotion": "4.0.356"
+      }
+    }
+  }
+}
+```
+
+## How It Works
+
+1. **Git Sparse Checkout**: The CLI uses git sparse checkout to efficiently fetch only the required directory from the repository
+2. **Local Installation**: Files are copied to `./core/<library-name>/` in your workspace
+3. **Dependency Management**: Required dependencies are automatically added to your `package.json`
+4. **Version Tracking**: The exact git commit hash is stored for reproducibility
+
+## Error Handling
+
+All errors are reported to stderr with clear, actionable messages:
+
+```bash
+# Missing token
+Error: WORKSPACE_CLI_TOKEN environment variable is required
+
+# Not in workspace
+Error: Not a workspace directory. Could not find package.json.
+
+# Library not found
+Error: Library 'invalid-name' not found in registry.
+Available libraries: animate-core
+
+# Already installed
+Error: Library 'animate-core' is already installed at version 0.1.3.
+Use --force to reinstall.
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+
+# Development mode (watch)
+npm run dev
+```
+
+## Adding New Libraries
+
+To add a new library to the registry:
+
+1. Add the library definition to `src/registry/libraries.json`
+2. Ensure the library source is available in a git repository
+3. Test installation with `workspace-cli add <library-name>`
+
+Example:
+```json
+{
+  "my-library": {
+    "name": "@aspects-ai/my-library",
+    "description": "Description of the library",
+    "version": "1.0.0",
+    "repository": {
+      "url": "https://github.com/org/repo.git",
+      "directory": "path/to/library/src",
+      "branch": "main"
+    },
+    "installPath": "my-library",
+    "dependencies": {
+      "react": "^18.0.0"
+    }
+  }
+}
+```
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command4 } from "commander";
+
+// src/commands/init.ts
+import { Command } from "commander";
+
+// src/utils/fs.ts
+import fs from "fs-extra";
+import path from "path";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+async function findWorkspaceRoot(startDir = process.cwd()) {
+  let currentDir = startDir;
+  while (currentDir !== path.parse(currentDir).root) {
+    const packageJsonPath = path.join(currentDir, "package.json");
+    if (await fs.pathExists(packageJsonPath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+  return null;
+}
+async function ensureWorkspaceRoot() {
+  const workspaceRoot = await findWorkspaceRoot();
+  if (!workspaceRoot) {
+    throw new Error(
+      "Not a workspace directory. Could not find package.json.\nRun this command from within a workspace directory."
+    );
+  }
+  return workspaceRoot;
+}
+function getRegistryPath() {
+  const prodPath = path.resolve(__dirname, "registry/libraries.json");
+  if (fs.existsSync(prodPath)) {
+    return prodPath;
+  }
+  return path.resolve(__dirname, "../registry/libraries.json");
+}
+async function readJsonFile(filePath) {
+  try {
+    return await fs.readJson(filePath);
+  } catch (error) {
+    throw new Error(`Failed to read ${filePath}: ${error}`);
+  }
+}
+async function writeJsonFile(filePath, data) {
+  try {
+    await fs.writeJson(filePath, data, { spaces: 2 });
+  } catch (error) {
+    throw new Error(`Failed to write ${filePath}: ${error}`);
+  }
+}
+
+// src/core/config.ts
+import { z } from "zod";
+import path2 from "path";
+import fs2 from "fs-extra";
+var LibraryInstallSchema = z.object({
+  version: z.string(),
+  installedAt: z.string(),
+  commit: z.string()
+});
+var WorkspaceConfigSchema = z.object({
+  version: z.string(),
+  coreDir: z.string(),
+  libraries: z.record(LibraryInstallSchema)
+});
+var CONFIG_FILE_NAME = "workspace.config.json";
+async function loadWorkspaceConfig(workspaceRoot) {
+  const configPath = path2.join(workspaceRoot, CONFIG_FILE_NAME);
+  if (!await fs2.pathExists(configPath)) {
+    return null;
+  }
+  const data = await readJsonFile(configPath);
+  return WorkspaceConfigSchema.parse(data);
+}
+async function saveWorkspaceConfig(workspaceRoot, config) {
+  const configPath = path2.join(workspaceRoot, CONFIG_FILE_NAME);
+  await writeJsonFile(configPath, config);
+}
+async function createDefaultConfig(workspaceRoot) {
+  const config = {
+    version: "1.0",
+    coreDir: "./core",
+    libraries: {}
+  };
+  await saveWorkspaceConfig(workspaceRoot, config);
+  return config;
+}
+async function getOrCreateConfig(workspaceRoot) {
+  const existing = await loadWorkspaceConfig(workspaceRoot);
+  if (existing) {
+    return existing;
+  }
+  return createDefaultConfig(workspaceRoot);
+}
+async function addLibraryToConfig(workspaceRoot, libraryName, version, commit) {
+  const config = await getOrCreateConfig(workspaceRoot);
+  config.libraries[libraryName] = {
+    version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    commit
+  };
+  await saveWorkspaceConfig(workspaceRoot, config);
+}
+async function isLibraryInstalled(workspaceRoot, libraryName) {
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  return config ? libraryName in config.libraries : false;
+}
+function getConfigPath(workspaceRoot) {
+  return path2.join(workspaceRoot, CONFIG_FILE_NAME);
+}
+
+// src/utils/logger.ts
+import chalk from "chalk";
+var logger = {
+  info(message) {
+    console.log(chalk.blue("[INFO]"), message);
+  },
+  success(message) {
+    console.log(chalk.green("[SUCCESS]"), message);
+  },
+  error(message) {
+    console.error(chalk.red("[ERROR]"), message);
+  },
+  warn(message) {
+    console.warn(chalk.yellow("[WARN]"), message);
+  },
+  log(message) {
+    console.log(message);
+  }
+};
+
+// src/commands/init.ts
+function createInitCommand() {
+  return new Command("init").description("Initialize workspace configuration").action(async () => {
+    try {
+      const workspaceRoot = await ensureWorkspaceRoot();
+      const existing = await loadWorkspaceConfig(workspaceRoot);
+      if (existing) {
+        logger.warn("workspace.config.json already exists");
+        logger.info(`Config file: ${getConfigPath(workspaceRoot)}`);
+        return;
+      }
+      await createDefaultConfig(workspaceRoot);
+      logger.success("Created workspace.config.json");
+      logger.log("\nNext steps:");
+      logger.log("  workspace-cli list          # View available libraries");
+      logger.log("  workspace-cli add <library> # Install a library");
+    } catch (error) {
+      logger.error(error.message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/list.ts
+import { Command as Command2 } from "commander";
+
+// src/core/registry.ts
+import { z as z2 } from "zod";
+var RepositorySchema = z2.object({
+  url: z2.string(),
+  directory: z2.string(),
+  branch: z2.string()
+});
+var LibrarySchema = z2.object({
+  name: z2.string(),
+  description: z2.string(),
+  version: z2.string(),
+  repository: RepositorySchema,
+  installPath: z2.string(),
+  dependencies: z2.record(z2.string())
+});
+var RegistrySchema = z2.object({
+  libraries: z2.record(LibrarySchema)
+});
+var cachedRegistry = null;
+async function loadRegistry() {
+  if (cachedRegistry) {
+    return cachedRegistry;
+  }
+  const registryPath = getRegistryPath();
+  const data = await readJsonFile(registryPath);
+  cachedRegistry = RegistrySchema.parse(data);
+  return cachedRegistry;
+}
+async function getLibrary(libraryName) {
+  const registry = await loadRegistry();
+  const library = registry.libraries[libraryName];
+  if (!library) {
+    throw new Error(
+      `Library '${libraryName}' not found in registry.
+Available libraries: ${Object.keys(registry.libraries).join(", ")}`
+    );
+  }
+  return library;
+}
+async function listLibraries() {
+  const registry = await loadRegistry();
+  return Object.entries(registry.libraries).map(([name, library]) => ({
+    name,
+    library
+  }));
+}
+
+// src/commands/list.ts
+import chalk2 from "chalk";
+function createListCommand() {
+  return new Command2("list").description("List available libraries").action(async () => {
+    try {
+      const libraries = await listLibraries();
+      logger.log(chalk2.bold("\nAvailable libraries:\n"));
+      for (const { name, library } of libraries) {
+        logger.log(chalk2.cyan(`  ${name}`) + chalk2.gray(` @${library.version}`));
+        logger.log(`    ${library.description}`);
+        logger.log("");
+      }
+      logger.log(`Total: ${libraries.length} ${libraries.length === 1 ? "library" : "libraries"}
+`);
+    } catch (error) {
+      logger.error(error.message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/add.ts
+import { Command as Command3 } from "commander";
+
+// src/core/installer.ts
+import path4 from "path";
+import fs4 from "fs-extra";
+
+// src/core/git-fetcher.ts
+import { execa } from "execa";
+import fs3 from "fs-extra";
+import path3 from "path";
+import os from "os";
+async function fetchDirectory(options) {
+  const tempDir = await fs3.mkdtemp(path3.join(os.tmpdir(), "workspace-cli-"));
+  try {
+    const repoUrl = options.repository.replace(
+      "https://github.com/",
+      `https://${options.token}@github.com/`
+    );
+    await execa("git", ["init"], { cwd: tempDir });
+    await execa("git", ["remote", "add", "origin", repoUrl], { cwd: tempDir });
+    await execa("git", ["config", "core.sparseCheckout", "true"], { cwd: tempDir });
+    const sparseFile = path3.join(tempDir, ".git", "info", "sparse-checkout");
+    await fs3.writeFile(sparseFile, `${options.directory}/*
+`);
+    await execa("git", ["pull", "origin", options.branch, "--depth=1"], {
+      cwd: tempDir,
+      stderr: "pipe"
+    });
+    const { stdout: commit } = await execa("git", ["rev-parse", "HEAD"], { cwd: tempDir });
+    const sourceDir = path3.join(tempDir, options.directory);
+    if (!await fs3.pathExists(sourceDir)) {
+      throw new Error(`Directory '${options.directory}' not found in repository`);
+    }
+    await fs3.ensureDir(options.targetPath);
+    await fs3.copy(sourceDir, options.targetPath, {
+      overwrite: true,
+      errorOnExist: false
+    });
+    return commit.trim();
+  } catch (error) {
+    if (error.stderr && error.stderr.includes("Authentication failed")) {
+      throw new Error(
+        "Git authentication failed. Please check your WORKSPACE_CLI_TOKEN.\nThe token must have access to the repository."
+      );
+    }
+    throw new Error(`Failed to fetch library from git: ${error.message}`);
+  } finally {
+    await fs3.remove(tempDir);
+  }
+}
+function getToken() {
+  const token = process.env.WORKSPACE_CLI_TOKEN;
+  if (!token) {
+    throw new Error(
+      "WORKSPACE_CLI_TOKEN environment variable is required.\nPlease set it with your GitHub personal access token:\n  export WORKSPACE_CLI_TOKEN=ghp_xxxxxxxxxxxx\n\nThe token needs read access to the repository."
+    );
+  }
+  return token;
+}
+
+// src/core/installer.ts
+async function installLibrary(workspaceRoot, libraryName, options = {}) {
+  if (!options.force && await isLibraryInstalled(workspaceRoot, libraryName)) {
+    const config2 = await loadWorkspaceConfig(workspaceRoot);
+    const existingVersion = config2?.libraries[libraryName]?.version;
+    throw new Error(
+      `Library '${libraryName}' is already installed at version ${existingVersion}.
+Use --force to reinstall.`
+    );
+  }
+  logger.info(`Fetching ${libraryName} metadata...`);
+  const library = await getLibrary(libraryName);
+  const token = getToken();
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const coreDir = config?.coreDir || "./core";
+  const targetPath = path4.join(workspaceRoot, coreDir, library.installPath);
+  logger.info(`Fetching ${libraryName}@${library.version} from git...`);
+  const commit = await fetchDirectory({
+    repository: library.repository.url,
+    directory: library.repository.directory,
+    branch: library.repository.branch,
+    token,
+    targetPath
+  });
+  logger.info(`Installed to ${path4.relative(workspaceRoot, targetPath)}`);
+  logger.info(`Updating workspace.config.json...`);
+  await addLibraryToConfig(workspaceRoot, libraryName, library.version, commit);
+  await updatePackageDependencies(workspaceRoot, library.dependencies);
+  logger.success(
+    `Installed ${libraryName}@${library.version} (commit: ${commit.substring(0, 7)})`
+  );
+}
+async function updatePackageDependencies(workspaceRoot, dependencies) {
+  const packageJsonPath = path4.join(workspaceRoot, "package.json");
+  if (!await fs4.pathExists(packageJsonPath)) {
+    logger.warn("No package.json found, skipping dependency updates");
+    return;
+  }
+  logger.info("Adding dependencies to package.json...");
+  const packageJson = await fs4.readJson(packageJsonPath);
+  packageJson.dependencies = packageJson.dependencies || {};
+  let addedCount = 0;
+  for (const [dep, version] of Object.entries(dependencies)) {
+    if (!packageJson.dependencies[dep]) {
+      packageJson.dependencies[dep] = version;
+      addedCount++;
+    }
+  }
+  if (addedCount > 0) {
+    await fs4.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+    logger.info(`Added ${addedCount} ${addedCount === 1 ? "dependency" : "dependencies"}`);
+  } else {
+    logger.info("All dependencies already present");
+  }
+}
+
+// src/commands/add.ts
+import chalk3 from "chalk";
+function createAddCommand() {
+  return new Command3("add").description("Add a library to the workspace").argument("<library>", "Name of the library to add").option("-f, --force", "Force reinstall if already installed").action(async (libraryName, options) => {
+    try {
+      const workspaceRoot = await ensureWorkspaceRoot();
+      await getOrCreateConfig(workspaceRoot);
+      await installLibrary(workspaceRoot, libraryName, { force: options.force });
+      logger.log("\n" + chalk3.bold("Next steps:"));
+      logger.log(`  ${chalk3.gray("Import components:")} import { ... } from '@/core/${libraryName.replace("animate-", "")}'`);
+      logger.log(`  ${chalk3.gray("Install dependencies:")} npm install`);
+      logger.log("");
+    } catch (error) {
+      logger.error(error.message);
+      process.exit(1);
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command4();
+program.name("workspace-cli").description("Lightweight CLI for installing libraries into workspaces").version("0.1.0");
+program.addCommand(createInitCommand());
+program.addCommand(createListCommand());
+program.addCommand(createAddCommand());
+program.parse(process.argv);

package/dist/registry/libraries.json

@@ -0,0 +1,31 @@
+{
+  "libraries": {
+    "animate-core": {
+      "name": "@aspects-ai/noodle-animate-core",
+      "description": "Core animation components for Noodle videos",
+      "version": "0.1.3",
+      "repository": {
+        "url": "https://github.com/aspects-ai/noodle-templates.git",
+        "directory": "noodle-animate-core/src",
+        "branch": "main"
+      },
+      "installPath": "animate-core",
+      "dependencies": {
+        "react": "19.1.0",
+        "react-dom": "19.1.0",
+        "remotion": "4.0.356",
+        "react-rnd": "^10.5.2",
+        "class-variance-authority": "^0.7.1",
+        "clsx": "^2.1.1",
+        "cmdk": "^1.1.1",
+        "date-fns": "^4.1.0",
+        "embla-carousel-react": "^8.6.0",
+        "input-otp": "^1.4.2",
+        "lucide-react": "^0.542.0",
+        "tailwind-merge": "^3.3.1",
+        "tailwindcss-animate": "^1.0.7",
+        "vaul": "^1.1.2"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aspects-ai/workspace-cli",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Lightweight CLI for installing libraries into workspaces",
+  "type": "module",
+  "bin": {
+    "workspace-cli": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean && npm run copy:registry",
+    "copy:registry": "mkdir -p dist/registry && cp src/registry/libraries.json dist/registry/",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "src/registry"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "execa": "^8.0.0",
+    "fs-extra": "^11.2.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/fs-extra": "^11.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/registry/libraries.json

@@ -0,0 +1,31 @@
+{
+  "libraries": {
+    "animate-core": {
+      "name": "@aspects-ai/noodle-animate-core",
+      "description": "Core animation components for Noodle videos",
+      "version": "0.1.3",
+      "repository": {
+        "url": "https://github.com/aspects-ai/noodle-templates.git",
+        "directory": "noodle-animate-core/src",
+        "branch": "main"
+      },
+      "installPath": "animate-core",
+      "dependencies": {
+        "react": "19.1.0",
+        "react-dom": "19.1.0",
+        "remotion": "4.0.356",
+        "react-rnd": "^10.5.2",
+        "class-variance-authority": "^0.7.1",
+        "clsx": "^2.1.1",
+        "cmdk": "^1.1.1",
+        "date-fns": "^4.1.0",
+        "embla-carousel-react": "^8.6.0",
+        "input-otp": "^1.4.2",
+        "lucide-react": "^0.542.0",
+        "tailwind-merge": "^3.3.1",
+        "tailwindcss-animate": "^1.0.7",
+        "vaul": "^1.1.2"
+      }
+    }
+  }
+}