feat(import): support local folder imports and enhance manifest handling

Author: moazbuilds

src/cli/commands/import.command.ts

@@ -5,10 +5,15 @@
  *   codemachine import <source>           Install/update an import
  *   codemachine import --list             List installed imports
  *   codemachine import --remove <name>    Remove an import
+ *
+ * Source formats:
+ *   - Local path: /path/to/folder or ./relative/path (requires .codemachine.json)
+ *   - GitHub: package-name, owner/repo, or https://github.com/...
+ *   - Git URL: git@github.com:user/repo.git
  */
 
 import type { Command } from 'commander';
-import { existsSync, rmSync } from 'node:fs';
+import { existsSync, rmSync, cpSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import {
@@ -82,6 +87,25 @@ function removeGitDir(repoPath: string): void {
   }
 }
 
+/**
+ * Copy a local folder to the imports directory
+ */
+function copyLocalFolder(
+  sourcePath: string,
+  destPath: string,
+  verbose: boolean
+): void {
+  if (verbose) {
+    console.log(`  Copying from: ${sourcePath}`);
+    console.log(`  Copying to: ${destPath}`);
+  }
+
+  cpSync(sourcePath, destPath, { recursive: true });
+
+  // Remove .git directory if present in the copied folder
+  removeGitDir(destPath);
+}
+
 /**
  * Install an import from a source
  */
@@ -114,12 +138,18 @@ async function installImport(source: string, verbose: boolean): Promise<void> {
   // Ensure imports directory exists
   ensureImportsDir();
 
-  // Clone the repository
-  console.log('  Cloning repository...');
-  await cloneRepo(resolved.url, installPath, verbose);
+  // Handle local paths vs git URLs
+  if (resolved.type === 'local-path') {
+    console.log('  Copying local folder...');
+    copyLocalFolder(resolved.url, installPath, verbose);
+  } else {
+    // Clone the repository
+    console.log('  Cloning repository...');
+    await cloneRepo(resolved.url, installPath, verbose);
 
-  // Remove .git directory (we don't need version control for imports)
-  removeGitDir(installPath);
+    // Remove .git directory (we don't need version control for imports)
+    removeGitDir(installPath);
+  }
 
   // Validate the import
   console.log('  Validating...');
@@ -198,6 +228,7 @@ function listImports(): void {
     console.log(`  codemachine import <package-name>`);
     console.log(`  codemachine import <owner>/<repo>`);
     console.log(`  codemachine import <https://github.com/...>`);
+    console.log(`  codemachine import </path/to/folder>  (local with .codemachine.json)`);
     return;
   }
 
@@ -246,6 +277,8 @@ async function runImportCommand(
       console.log(`  codemachine import <package-name>`);
       console.log(`  codemachine import <owner>/<repo>`);
       console.log(`  codemachine import <https://github.com/...>`);
+      console.log(`  codemachine import </path/to/folder>   (local path with .codemachine.json)`);
+      console.log(`  codemachine import <./relative/path>   (local path with .codemachine.json)`);
       console.log('\nOther options:');
       console.log('  codemachine import --list            List installed imports');
       console.log('  codemachine import --remove <name>   Remove an import');

src/cli/tui/routes/home/dialogs/import-dialog.tsx

@@ -36,12 +36,45 @@ export interface ImportDialogProps {
 }
 
 /**
- * Parse input to extract owner/repo and generate GitHub URL
+ * Parse input to extract owner/repo, GitHub URL, or local path
  */
-function parseGitHubInput(input: string): { owner?: string; repo: string; url?: string } | null {
+function parseGitHubInput(input: string): { owner?: string; repo: string; url?: string; isLocal?: boolean } | null {
   const trimmed = input.trim()
   if (!trimmed) return null
 
+  // Local path: absolute path starting with /
+  if (trimmed.startsWith('/')) {
+    const parts = trimmed.split('/')
+    const repo = parts[parts.length - 1] || 'local-import'
+    return {
+      repo,
+      url: trimmed,
+      isLocal: true,
+    }
+  }
+
+  // Local path: relative path starting with ./ or ../
+  if (trimmed.startsWith('./') || trimmed.startsWith('../')) {
+    const parts = trimmed.split('/')
+    const repo = parts[parts.length - 1] || 'local-import'
+    return {
+      repo,
+      url: trimmed,
+      isLocal: true,
+    }
+  }
+
+  // Local path: home directory shorthand ~/
+  if (trimmed.startsWith('~/')) {
+    const parts = trimmed.split('/')
+    const repo = parts[parts.length - 1] || 'local-import'
+    return {
+      repo,
+      url: trimmed,
+      isLocal: true,
+    }
+  }
+
   // Full GitHub URL: https://github.com/owner/repo or https://github.com/owner/repo.git
   const urlMatch = trimmed.match(/^https?:\/\/github\.com\/([^\/]+)\/([^\/\s]+?)(?:\.git)?$/i)
   if (urlMatch) {
@@ -101,11 +134,12 @@ export function ImportDialog(props: ImportDialogProps) {
     if (!source) return
 
     appDebug("[ImportDialog] Starting install process")
+    const isLocalPath = parsed()?.isLocal ?? false
     setState({
       phase: "installing",
       steps: [
         { label: "Resolving source", status: "active" },
-        { label: "Cloning repository", status: "pending" },
+        { label: isLocalPath ? "Copying folder" : "Cloning repository", status: "pending" },
         { label: "Validating manifest", status: "pending" },
         { label: "Registering package", status: "pending" },
       ],
@@ -277,7 +311,7 @@ export function ImportDialog(props: ImportDialogProps) {
                 <box flexDirection="column" width={50}>
                   <Show when={p}>
                     <text fg={theme.theme.textMuted} marginBottom={1}>
-                      {p!.owner}/{p!.repo}
+                      {p!.isLocal ? `📁 ${p!.repo}` : p!.owner ? `${p!.owner}/${p!.repo}` : p!.repo}
                     </text>
                   </Show>
 
@@ -298,7 +332,7 @@ export function ImportDialog(props: ImportDialogProps) {
         <box flexDirection="column" width={50}>
           {/* Title */}
           <text fg={theme.theme.primary} attributes={1} marginBottom={1}>
-            ⬇ Add Workflow from GitHub
+            ⬇ Add Workflow Package
           </text>
 
           {/* Input field */}
@@ -312,7 +346,7 @@ export function ImportDialog(props: ImportDialogProps) {
           >
             <input
               value={inputValue()}
-              placeholder="owner/repo"
+              placeholder="owner/repo or /path/to/folder"
               onInput={setInputValue}
               onPaste={handlePaste}
               focused={true}
@@ -325,14 +359,14 @@ export function ImportDialog(props: ImportDialogProps) {
           <box marginBottom={1} minHeight={2}>
             <Show when={validation().status === "empty"}>
               <text fg={theme.theme.textMuted}>
-                Enter repo name or paste full GitHub URL
+                Enter repo name, GitHub URL, or local path
               </text>
             </Show>
 
             <Show when={validation().status === "valid" && parsed()}>
               <box flexDirection="column">
                 <text fg={theme.theme.success}>
-                  ↳ {parsed()!.url || parsed()!.repo}
+                  {parsed()!.isLocal ? "📁" : "↳"} {parsed()!.url || parsed()!.repo}
                 </text>
               </box>
             </Show>

src/cli/tui/routes/home/hooks/use-home-commands.tsx

@@ -111,7 +111,7 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
     // Add import option at the top (no category)
     const selectOptions = [
       {
-        title: "⬇ Import template from GitHub",
+        title: "⬇ Import template (GitHub or local)",
         value: IMPORT_ACTION,
       },
       ...templateOptions,
@@ -322,7 +322,7 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
       isImportInstalled,
       ensureImportsDir,
     } = await import("../../../../../shared/imports/index.js")
-    const { existsSync, rmSync } = await import("node:fs")
+    const { existsSync, rmSync, cpSync } = await import("node:fs")
     const { spawn } = await import("node:child_process")
 
     const cloneRepo = (url: string, destPath: string): Promise<void> => {
@@ -351,6 +351,10 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
       })
     }
 
+    const copyLocalFolder = (sourcePath: string, destPath: string): void => {
+      cpSync(sourcePath, destPath, { recursive: true })
+    }
+
     const removeGitDir = (repoPath: string): void => {
       const { join } = require("node:path")
       const gitDir = join(repoPath, ".git")
@@ -361,7 +365,7 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
 
     const performInstall = async (source: string) => {
       try {
-        // Resolve the source to a clone URL
+        // Resolve the source to a clone URL or local path
         const resolved = await resolveSource(source)
         const installPath = getImportInstallPath(resolved.repoName)
 
@@ -373,10 +377,15 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
         // Ensure imports directory exists
         ensureImportsDir()
 
-        // Clone the repository
-        await cloneRepo(resolved.url, installPath)
+        // Handle local paths vs git URLs
+        if (resolved.type === "local-path") {
+          copyLocalFolder(resolved.url, installPath)
+        } else {
+          // Clone the repository
+          await cloneRepo(resolved.url, installPath)
+        }
 
-        // Remove .git directory
+        // Remove .git directory (in case local folder had one)
         removeGitDir(installPath)
 
         // Validate the import
@@ -394,9 +403,11 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
           if (hasMissingManifest) {
             return {
               success: false,
-              error: "Missing codemachine.json file",
+              error: "Missing manifest file",
               errorDetails:
-                "The repository must contain a codemachine.json manifest file in the root directory.",
+                resolved.type === "local-path"
+                  ? "The folder must contain a .codemachine.json or codemachine.json manifest file."
+                  : "The repository must contain a codemachine.json manifest file in the root directory.",
             }
           }
 
@@ -446,6 +457,22 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
           }
         }
 
+        if (errorMessage.includes("ENOENT") || errorMessage.includes("no such file")) {
+          return {
+            success: false,
+            error: "Local folder not found",
+            errorDetails: "Check that the path exists and is accessible.",
+          }
+        }
+
+        if (errorMessage.includes("EACCES") || errorMessage.includes("permission denied")) {
+          return {
+            success: false,
+            error: "Permission denied",
+            errorDetails: "Check that you have read access to the folder.",
+          }
+        }
+
         return {
           success: false,
           error: errorMessage,

src/shared/imports/index.ts

@@ -29,6 +29,7 @@ export {
 // Manifest parsing
 export {
   parseManifest,
+  findManifestPath,
   getResolvedPaths,
   validateImport,
   getManifestFilename,

src/shared/imports/manifest.ts

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import type { ImportManifest, ValidationResult } from './types.js';
 
 const MANIFEST_FILENAME = 'codemachine.json';
+const LOCAL_MANIFEST_FILENAME = '.codemachine.json';
 
 /**
  * Default paths following CodeMachine conventions
@@ -18,13 +19,32 @@ const DEFAULT_PATHS = {
   characters: 'config/agent-characters.json',
 };
 
+/**
+ * Find the manifest file path (checks both codemachine.json and .codemachine.json)
+ */
+export function findManifestPath(importPath: string): string | null {
+  // Check for .codemachine.json first (local imports)
+  const localManifestPath = join(importPath, LOCAL_MANIFEST_FILENAME);
+  if (existsSync(localManifestPath)) {
+    return localManifestPath;
+  }
+
+  // Check for codemachine.json (standard imports)
+  const manifestPath = join(importPath, MANIFEST_FILENAME);
+  if (existsSync(manifestPath)) {
+    return manifestPath;
+  }
+
+  return null;
+}
+
 /**
  * Parse a manifest file from a directory
  */
 export function parseManifest(importPath: string): ImportManifest | null {
-  const manifestPath = join(importPath, MANIFEST_FILENAME);
+  const manifestPath = findManifestPath(importPath);
 
-  if (!existsSync(manifestPath)) {
+  if (!manifestPath) {
     return null;
   }
 
@@ -66,7 +86,7 @@ export function validateImport(importPath: string): ValidationResult {
   // Check manifest exists
   const manifest = parseManifest(importPath);
   if (!manifest) {
-    errors.push(`Missing ${MANIFEST_FILENAME} file`);
+    errors.push(`Missing manifest file (${MANIFEST_FILENAME} or ${LOCAL_MANIFEST_FILENAME})`);
     return { valid: false, errors, warnings };
   }