clawchef 0.1.3 → 0.1.5

package/README.md

@@ -8,6 +8,7 @@ Recipe-driven OpenClaw environment orchestrator.
 - Accepts recipe input from local file/dir/archive and HTTP URL/archive.
 - Resolves `${var}` parameters from `--var`, environment, and defaults.
 - Auto-loads environment variables from `.env` in the current working directory.
+- Supports loading env vars from a custom `.env` path/URL via `--env-file`.
 - Requires secrets to be injected via `--var` / `CLAWCHEF_VAR_*` (no inline secrets in recipe).
 - Prepares OpenClaw version (install or reuse).
 - When installed OpenClaw version mismatches recipe version, prompts: ignore / abort / force reinstall (silent mode auto-picks force reinstall).
@@ -39,6 +40,19 @@ Run recipe from URL:
 clawchef cook https://example.com/recipes/sample.yaml --provider remote
 ```
 
+Run with custom env file (local path or HTTP URL):
+
+```bash
+clawchef cook recipes/sample.yaml --env-file ./.env.staging
+clawchef cook recipes/sample.yaml --env-file https://example.com/envs/staging.env
+```
+
+Run recipe from GitHub repository root (`recipe.yaml` at repo root):
+
+```bash
+clawchef cook https://github.com/renorzr/loom-plus-recipe
+```
+
 Run recipe from archive (default `recipe.yaml`):
 
 ```bash
@@ -184,6 +198,7 @@ await scaffold("./my-recipe-project", {
 - `plugins`: plugin npm specs to preinstall for this run (`string[]`)
 - `provider`: `command | remote | mock`
 - `remote`: remote provider config (same fields as CLI remote flags)
+- `envFile`: custom env file path/URL; when set, default cwd `.env` loading is skipped
 - `dryRun`, `allowMissing`, `verbose`
 - `silent` (default: `true` in Node API)
 - `loadDotEnvFromCwd` (default: `true`)
@@ -206,6 +221,7 @@ Notes:
 If `params.<key>.required: true` and no value is found, run fails.
 
 If `.env` exists in the directory where `clawchef` is executed, it is loaded before recipe parsing.
+If `--env-file` (or Node API `envFile`) is provided, only that env source is loaded.
 
 ## Recipe reference formats
 
@@ -219,6 +235,7 @@ If `.env` exists in the directory where `clawchef` is executed, it is loaded bef
 - `https://host/recipe.yaml`
 - `https://host/archive.zip` (loads `recipe.yaml` from archive)
 - `https://host/archive.zip:custom/recipe.yaml`
+- `https://github.com/<owner>/<repo>` (loads `recipe.yaml` from repo root)
 
 Supported archives: `.zip`, `.tar`, `.tar.gz`, `.tgz`.
 

package/dist/api.d.ts

@@ -9,6 +9,7 @@ export interface CookOptions {
     silent?: boolean;
     provider?: OpenClawProvider;
     remote?: Partial<OpenClawRemoteConfig>;
+    envFile?: string;
     loadDotEnvFromCwd?: boolean;
 }
 export declare function cook(recipeRef: string, options?: CookOptions): Promise<void>;

package/dist/api.js

@@ -1,6 +1,6 @@
 import YAML from "js-yaml";
 import { ClawChefError } from "./errors.js";
-import { importDotEnvFromCwd } from "./env.js";
+import { importDotEnvFromCwd, importDotEnvFromRef } from "./env.js";
 import { Logger } from "./logger.js";
 import { runRecipe } from "./orchestrator.js";
 import { loadRecipe, loadRecipeText } from "./recipe.js";
@@ -21,7 +21,10 @@ function normalizeCookOptions(options) {
     };
 }
 export async function cook(recipeRef, options = {}) {
-    if (options.loadDotEnvFromCwd ?? true) {
+    if (options.envFile) {
+        await importDotEnvFromRef(options.envFile);
+    }
+    else if (options.loadDotEnvFromCwd ?? true) {
         importDotEnvFromCwd();
     }
     const runOptions = normalizeCookOptions(options);

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { ClawChefError } from "./errors.js";
+import { importDotEnvFromCwd, importDotEnvFromRef } from "./env.js";
 import { Logger } from "./logger.js";
 import { runRecipe } from "./orchestrator.js";
 import { loadRecipe, loadRecipeText } from "./recipe.js";
@@ -78,6 +79,7 @@ export function buildCli() {
         .option("--verbose", "Verbose logging", false)
         .option("-s, --silent", "Skip reset confirmation prompt", false)
         .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
+        .option("--env-file <path-or-url>", "Load env vars from local file or HTTP URL")
         .option("--provider <provider>", "Execution provider: command | remote | mock")
         .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p) => p.concat([v]), [])
         .option("--remote-base-url <url>", "Remote OpenClaw API base URL")
@@ -87,6 +89,12 @@ export function buildCli() {
         .option("--remote-timeout-ms <ms>", "Remote operation timeout in milliseconds")
         .option("--remote-operation-path <path>", "Remote operation endpoint path")
         .action(async (recipeRef, opts) => {
+        if (opts.envFile) {
+            await importDotEnvFromRef(String(opts.envFile));
+        }
+        else {
+            importDotEnvFromCwd();
+        }
         const provider = parseProvider(opts.provider ?? readEnv("CLAWCHEF_PROVIDER") ?? "command");
         const options = {
             vars: parseVarFlags(opts.var),

package/dist/env.d.ts

@@ -1 +1,2 @@
 export declare function importDotEnvFromCwd(): void;
+export declare function importDotEnvFromRef(ref: string): Promise<void>;

package/dist/env.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { config as loadDotenv } from "dotenv";
+import { config as loadDotenv, parse as parseDotenv } from "dotenv";
 import { ClawChefError } from "./errors.js";
 export function importDotEnvFromCwd() {
     const envPath = path.resolve(process.cwd(), ".env");
@@ -12,3 +13,51 @@ export function importDotEnvFromCwd() {
         throw new ClawChefError(`Failed to load .env from current directory: ${result.error.message}`);
     }
 }
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function applyEnv(entries) {
+    for (const [key, value] of Object.entries(entries)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+export async function importDotEnvFromRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed) {
+        throw new ClawChefError("--env-file cannot be empty");
+    }
+    if (isHttpUrl(trimmed)) {
+        let response;
+        try {
+            response = await fetch(trimmed);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new ClawChefError(`Failed to fetch env file URL ${trimmed}: ${message}`);
+        }
+        if (!response.ok) {
+            throw new ClawChefError(`Failed to fetch env file URL ${trimmed}: HTTP ${response.status}`);
+        }
+        const content = await response.text();
+        applyEnv(parseDotenv(content));
+        return;
+    }
+    const envPath = path.resolve(trimmed);
+    let content;
+    try {
+        content = await readFile(envPath, "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`Failed to load env file ${envPath}: ${message}`);
+    }
+    applyEnv(parseDotenv(content));
+}

package/dist/index.js

@@ -1,9 +1,7 @@
 #!/usr/bin/env node
 import { buildCli } from "./cli.js";
-import { importDotEnvFromCwd } from "./env.js";
 import { ClawChefError } from "./errors.js";
 async function main() {
-    importDotEnvFromCwd();
     const program = buildCli();
     await program.parseAsync(process.argv);
 }

package/dist/recipe.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
-import { readFile, mkdtemp, stat, writeFile, rm, mkdir } from "node:fs/promises";
+import { readFile, mkdtemp, stat, writeFile, rm, mkdir, readdir } from "node:fs/promises";
 import YAML from "js-yaml";
 import { recipeSchema } from "./schema.js";
 import { ClawChefError } from "./errors.js";
@@ -245,6 +245,128 @@ function parseUrlReference(input) {
         directUrl: parsed.toString(),
     };
 }
+function parseGitHubRepoReference(input) {
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return undefined;
+    }
+    if (parsed.hostname.toLowerCase() !== "github.com") {
+        return undefined;
+    }
+    if (parsed.search || parsed.hash) {
+        return undefined;
+    }
+    const parts = parsed.pathname.split("/").filter((part) => part.length > 0);
+    if (parts.length !== 2) {
+        return undefined;
+    }
+    const owner = parts[0];
+    const repo = parts[1].endsWith(".git") ? parts[1].slice(0, -4) : parts[1];
+    if (!owner || !repo) {
+        return undefined;
+    }
+    return { owner, repo };
+}
+async function resolveRecipePathFromExtracted(extractDir, recipeInArchive, missingMessage) {
+    const directPath = path.join(extractDir, recipeInArchive);
+    try {
+        const directStat = await stat(directPath);
+        if (directStat.isFile()) {
+            return directPath;
+        }
+        throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
+    }
+    catch (err) {
+        if (err instanceof ClawChefError) {
+            throw err;
+        }
+    }
+    const entries = await readdir(extractDir, { withFileTypes: true });
+    const matched = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidate = path.join(extractDir, entry.name, recipeInArchive);
+        try {
+            const s = await stat(candidate);
+            if (s.isFile()) {
+                matched.push(candidate);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    if (matched.length === 1) {
+        return matched[0];
+    }
+    if (matched.length > 1) {
+        throw new ClawChefError(`Multiple recipe files found in extracted archive for ${recipeInArchive}; provide explicit selector`);
+    }
+    throw new ClawChefError(missingMessage);
+}
+async function resolveGitHubRepoReference(recipeInput) {
+    const repoRef = parseGitHubRepoReference(recipeInput);
+    if (!repoRef) {
+        return undefined;
+    }
+    const repoApiUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}`;
+    const repoHeaders = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "clawchef",
+    };
+    let repoResponse;
+    try {
+        repoResponse = await fetch(repoApiUrl, { headers: repoHeaders });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: ${message}`);
+    }
+    if (!repoResponse.ok) {
+        throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: HTTP ${repoResponse.status}`);
+    }
+    const repoJson = (await repoResponse.json());
+    const defaultBranch = repoJson.default_branch?.trim();
+    if (!defaultBranch) {
+        throw new ClawChefError(`GitHub repository ${repoRef.owner}/${repoRef.repo} has no default branch`);
+    }
+    const tarballUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}/tarball/${encodeURIComponent(defaultBranch)}`;
+    let tarballResponse;
+    try {
+        tarballResponse = await fetch(tarballUrl, { headers: repoHeaders });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: ${message}`);
+    }
+    if (!tarballResponse.ok) {
+        throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: HTTP ${tarballResponse.status}`);
+    }
+    const tempDir = await mkdtemp(path.join(tmpdir(), "clawchef-recipe-"));
+    const archivePath = path.join(tempDir, "repo.tar.gz");
+    await writeFile(archivePath, Buffer.from(await tarballResponse.arrayBuffer()));
+    const extractDir = path.join(tempDir, "extracted");
+    await mkdir(extractDir, { recursive: true });
+    await extractArchive(archivePath, extractDir);
+    const recipePath = await resolveRecipePathFromExtracted(extractDir, DEFAULT_RECIPE_FILE, `Recipe file not found in GitHub repository root: ${DEFAULT_RECIPE_FILE}`);
+    return {
+        recipePath,
+        origin: {
+            kind: "local",
+            recipePath,
+            recipeDir: path.dirname(recipePath),
+        },
+        cleanupPaths: [tempDir],
+    };
+}
 async function runCommand(command, args) {
     await new Promise((resolve, reject) => {
         const child = spawn(command, args, {
@@ -287,6 +409,10 @@ async function extractArchive(archivePath, extractDir) {
 }
 async function resolveRecipeReference(recipeInput) {
     if (isHttpUrl(recipeInput)) {
+        const githubResolved = await resolveGitHubRepoReference(recipeInput);
+        if (githubResolved) {
+            return githubResolved;
+        }
         const parsed = parseUrlReference(recipeInput);
         if (parsed.directUrl) {
             let response;
@@ -334,16 +460,7 @@ async function resolveRecipeReference(recipeInput) {
         await rm(extractDir, { recursive: true, force: true });
         await mkdir(extractDir, { recursive: true });
         await extractArchive(downloadedArchivePath, extractDir);
-        const recipePath = path.join(extractDir, recipeInArchive);
-        try {
-            const s = await stat(recipePath);
-            if (!s.isFile()) {
-                throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
-            }
-        }
-        catch {
-            throw new ClawChefError(`Recipe file not found in archive: ${recipeInArchive}`);
-        }
+        const recipePath = await resolveRecipePathFromExtracted(extractDir, recipeInArchive, `Recipe file not found in archive: ${recipeInArchive}`);
         return {
             recipePath,
             origin: {
@@ -381,16 +498,7 @@ async function resolveRecipeReference(recipeInput) {
             const extractDir = path.join(tempDir, "extracted");
             await mkdir(extractDir, { recursive: true });
             await extractArchive(localPath, extractDir);
-            const recipePath = path.join(extractDir, DEFAULT_RECIPE_FILE);
-            try {
-                const s = await stat(recipePath);
-                if (!s.isFile()) {
-                    throw new ClawChefError(`Recipe in archive is not a file: ${DEFAULT_RECIPE_FILE}`);
-                }
-            }
-            catch {
-                throw new ClawChefError(`Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`);
-            }
+            const recipePath = await resolveRecipePathFromExtracted(extractDir, DEFAULT_RECIPE_FILE, `Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`);
             return {
                 recipePath,
                 origin: {
@@ -445,16 +553,7 @@ async function resolveRecipeReference(recipeInput) {
         const extractDir = path.join(tempDir, "extracted");
         await mkdir(extractDir, { recursive: true });
         await extractArchive(basePath, extractDir);
-        const recipePath = path.join(extractDir, selector);
-        try {
-            const s = await stat(recipePath);
-            if (!s.isFile()) {
-                throw new ClawChefError(`Recipe in archive is not a file: ${selector}`);
-            }
-        }
-        catch {
-            throw new ClawChefError(`Recipe file not found in archive: ${selector}`);
-        }
+        const recipePath = await resolveRecipePathFromExtracted(extractDir, selector, `Recipe file not found in archive: ${selector}`);
         return {
             recipePath,
             origin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawchef",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Recipe-driven OpenClaw environment orchestrator",
   "homepage": "https://renorzr.github.io/clawchef",
   "repository": {

package/src/api.ts

@@ -1,6 +1,6 @@
 import YAML from "js-yaml";
 import { ClawChefError } from "./errors.js";
-import { importDotEnvFromCwd } from "./env.js";
+import { importDotEnvFromCwd, importDotEnvFromRef } from "./env.js";
 import { Logger } from "./logger.js";
 import { runRecipe } from "./orchestrator.js";
 import { loadRecipe, loadRecipeText } from "./recipe.js";
@@ -18,6 +18,7 @@ export interface CookOptions {
   silent?: boolean;
   provider?: OpenClawProvider;
   remote?: Partial<OpenClawRemoteConfig>;
+  envFile?: string;
   loadDotEnvFromCwd?: boolean;
 }
 
@@ -37,7 +38,9 @@ function normalizeCookOptions(options: CookOptions): RunOptions {
 }
 
 export async function cook(recipeRef: string, options: CookOptions = {}): Promise<void> {
-  if (options.loadDotEnvFromCwd ?? true) {
+  if (options.envFile) {
+    await importDotEnvFromRef(options.envFile);
+  } else if (options.loadDotEnvFromCwd ?? true) {
     importDotEnvFromCwd();
   }
 

package/src/cli.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { ClawChefError } from "./errors.js";
+import { importDotEnvFromCwd, importDotEnvFromRef } from "./env.js";
 import { Logger } from "./logger.js";
 import { runRecipe } from "./orchestrator.js";
 import { loadRecipe, loadRecipeText } from "./recipe.js";
@@ -88,6 +89,7 @@ export function buildCli(): Command {
     .option("--verbose", "Verbose logging", false)
     .option("-s, --silent", "Skip reset confirmation prompt", false)
     .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
+    .option("--env-file <path-or-url>", "Load env vars from local file or HTTP URL")
     .option("--provider <provider>", "Execution provider: command | remote | mock")
     .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p: string[]) => p.concat([v]), [])
     .option("--remote-base-url <url>", "Remote OpenClaw API base URL")
@@ -97,6 +99,12 @@ export function buildCli(): Command {
     .option("--remote-timeout-ms <ms>", "Remote operation timeout in milliseconds")
     .option("--remote-operation-path <path>", "Remote operation endpoint path")
     .action(async (recipeRef: string, opts) => {
+      if (opts.envFile) {
+        await importDotEnvFromRef(String(opts.envFile));
+      } else {
+        importDotEnvFromCwd();
+      }
+
       const provider = parseProvider(opts.provider ?? readEnv("CLAWCHEF_PROVIDER") ?? "command");
       const options: RunOptions = {
         vars: parseVarFlags(opts.var),

package/src/env.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { config as loadDotenv } from "dotenv";
+import { config as loadDotenv, parse as parseDotenv } from "dotenv";
 import { ClawChefError } from "./errors.js";
 
 export function importDotEnvFromCwd(): void {
@@ -14,3 +15,53 @@ export function importDotEnvFromCwd(): void {
     throw new ClawChefError(`Failed to load .env from current directory: ${result.error.message}`);
   }
 }
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function applyEnv(entries: Record<string, string>): void {
+  for (const [key, value] of Object.entries(entries)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+export async function importDotEnvFromRef(ref: string): Promise<void> {
+  const trimmed = ref.trim();
+  if (!trimmed) {
+    throw new ClawChefError("--env-file cannot be empty");
+  }
+
+  if (isHttpUrl(trimmed)) {
+    let response: Response;
+    try {
+      response = await fetch(trimmed);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ClawChefError(`Failed to fetch env file URL ${trimmed}: ${message}`);
+    }
+    if (!response.ok) {
+      throw new ClawChefError(`Failed to fetch env file URL ${trimmed}: HTTP ${response.status}`);
+    }
+    const content = await response.text();
+    applyEnv(parseDotenv(content));
+    return;
+  }
+
+  const envPath = path.resolve(trimmed);
+  let content: string;
+  try {
+    content = await readFile(envPath, "utf8");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ClawChefError(`Failed to load env file ${envPath}: ${message}`);
+  }
+  applyEnv(parseDotenv(content));
+}

package/src/index.ts

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 import { buildCli } from "./cli.js";
-import { importDotEnvFromCwd } from "./env.js";
 import { ClawChefError } from "./errors.js";
 
 async function main(): Promise<void> {
-  importDotEnvFromCwd();
   const program = buildCli();
   await program.parseAsync(process.argv);
 }

package/src/recipe.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
-import { readFile, mkdtemp, stat, writeFile, rm, mkdir } from "node:fs/promises";
+import { readFile, mkdtemp, stat, writeFile, rm, mkdir, readdir } from "node:fs/promises";
 import YAML from "js-yaml";
 import { recipeSchema } from "./schema.js";
 import { ClawChefError } from "./errors.js";
@@ -266,6 +266,11 @@ interface ResolvedRecipeReference {
   cleanupPaths: string[];
 }
 
+interface GitHubRepoRef {
+  owner: string;
+  repo: string;
+}
+
 function isHttpUrl(value: string): boolean {
   try {
     const url = new URL(value);
@@ -323,6 +328,149 @@ function parseUrlReference(input: string): { archiveUrl: string; inner?: string;
   };
 }
 
+function parseGitHubRepoReference(input: string): GitHubRepoRef | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(input);
+  } catch {
+    return undefined;
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return undefined;
+  }
+  if (parsed.hostname.toLowerCase() !== "github.com") {
+    return undefined;
+  }
+  if (parsed.search || parsed.hash) {
+    return undefined;
+  }
+
+  const parts = parsed.pathname.split("/").filter((part) => part.length > 0);
+  if (parts.length !== 2) {
+    return undefined;
+  }
+
+  const owner = parts[0];
+  const repo = parts[1].endsWith(".git") ? parts[1].slice(0, -4) : parts[1];
+  if (!owner || !repo) {
+    return undefined;
+  }
+
+  return { owner, repo };
+}
+
+async function resolveRecipePathFromExtracted(
+  extractDir: string,
+  recipeInArchive: string,
+  missingMessage: string,
+): Promise<string> {
+  const directPath = path.join(extractDir, recipeInArchive);
+  try {
+    const directStat = await stat(directPath);
+    if (directStat.isFile()) {
+      return directPath;
+    }
+    throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
+  } catch (err) {
+    if (err instanceof ClawChefError) {
+      throw err;
+    }
+  }
+
+  const entries = await readdir(extractDir, { withFileTypes: true });
+  const matched: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const candidate = path.join(extractDir, entry.name, recipeInArchive);
+    try {
+      const s = await stat(candidate);
+      if (s.isFile()) {
+        matched.push(candidate);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  if (matched.length === 1) {
+    return matched[0];
+  }
+  if (matched.length > 1) {
+    throw new ClawChefError(`Multiple recipe files found in extracted archive for ${recipeInArchive}; provide explicit selector`);
+  }
+
+  throw new ClawChefError(missingMessage);
+}
+
+async function resolveGitHubRepoReference(recipeInput: string): Promise<ResolvedRecipeReference | undefined> {
+  const repoRef = parseGitHubRepoReference(recipeInput);
+  if (!repoRef) {
+    return undefined;
+  }
+
+  const repoApiUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}`;
+  const repoHeaders = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "clawchef",
+  };
+
+  let repoResponse: Response;
+  try {
+    repoResponse = await fetch(repoApiUrl, { headers: repoHeaders });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: ${message}`);
+  }
+  if (!repoResponse.ok) {
+    throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: HTTP ${repoResponse.status}`);
+  }
+
+  const repoJson = (await repoResponse.json()) as { default_branch?: string };
+  const defaultBranch = repoJson.default_branch?.trim();
+  if (!defaultBranch) {
+    throw new ClawChefError(`GitHub repository ${repoRef.owner}/${repoRef.repo} has no default branch`);
+  }
+
+  const tarballUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}/tarball/${encodeURIComponent(defaultBranch)}`;
+  let tarballResponse: Response;
+  try {
+    tarballResponse = await fetch(tarballUrl, { headers: repoHeaders });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: ${message}`);
+  }
+  if (!tarballResponse.ok) {
+    throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: HTTP ${tarballResponse.status}`);
+  }
+
+  const tempDir = await mkdtemp(path.join(tmpdir(), "clawchef-recipe-"));
+  const archivePath = path.join(tempDir, "repo.tar.gz");
+  await writeFile(archivePath, Buffer.from(await tarballResponse.arrayBuffer()));
+
+  const extractDir = path.join(tempDir, "extracted");
+  await mkdir(extractDir, { recursive: true });
+  await extractArchive(archivePath, extractDir);
+
+  const recipePath = await resolveRecipePathFromExtracted(
+    extractDir,
+    DEFAULT_RECIPE_FILE,
+    `Recipe file not found in GitHub repository root: ${DEFAULT_RECIPE_FILE}`,
+  );
+
+  return {
+    recipePath,
+    origin: {
+      kind: "local",
+      recipePath,
+      recipeDir: path.dirname(recipePath),
+    },
+    cleanupPaths: [tempDir],
+  };
+}
+
 async function runCommand(command: string, args: string[]): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     const child = spawn(command, args, {
@@ -370,6 +518,11 @@ async function extractArchive(archivePath: string, extractDir: string): Promise<
 
 async function resolveRecipeReference(recipeInput: string): Promise<ResolvedRecipeReference> {
   if (isHttpUrl(recipeInput)) {
+    const githubResolved = await resolveGitHubRepoReference(recipeInput);
+    if (githubResolved) {
+      return githubResolved;
+    }
+
     const parsed = parseUrlReference(recipeInput);
     if (parsed.directUrl) {
       let response: Response;
@@ -421,15 +574,11 @@ async function resolveRecipeReference(recipeInput: string): Promise<ResolvedReci
     await mkdir(extractDir, { recursive: true });
     await extractArchive(downloadedArchivePath, extractDir);
 
-    const recipePath = path.join(extractDir, recipeInArchive);
-    try {
-      const s = await stat(recipePath);
-      if (!s.isFile()) {
-        throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
-      }
-    } catch {
-      throw new ClawChefError(`Recipe file not found in archive: ${recipeInArchive}`);
-    }
+    const recipePath = await resolveRecipePathFromExtracted(
+      extractDir,
+      recipeInArchive,
+      `Recipe file not found in archive: ${recipeInArchive}`,
+    );
 
     return {
       recipePath,
@@ -470,15 +619,11 @@ async function resolveRecipeReference(recipeInput: string): Promise<ResolvedReci
       const extractDir = path.join(tempDir, "extracted");
       await mkdir(extractDir, { recursive: true });
       await extractArchive(localPath, extractDir);
-      const recipePath = path.join(extractDir, DEFAULT_RECIPE_FILE);
-      try {
-        const s = await stat(recipePath);
-        if (!s.isFile()) {
-          throw new ClawChefError(`Recipe in archive is not a file: ${DEFAULT_RECIPE_FILE}`);
-        }
-      } catch {
-        throw new ClawChefError(`Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`);
-      }
+      const recipePath = await resolveRecipePathFromExtracted(
+        extractDir,
+        DEFAULT_RECIPE_FILE,
+        `Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`,
+      );
       return {
         recipePath,
         origin: {
@@ -538,15 +683,11 @@ async function resolveRecipeReference(recipeInput: string): Promise<ResolvedReci
     const extractDir = path.join(tempDir, "extracted");
     await mkdir(extractDir, { recursive: true });
     await extractArchive(basePath, extractDir);
-    const recipePath = path.join(extractDir, selector);
-    try {
-      const s = await stat(recipePath);
-      if (!s.isFile()) {
-        throw new ClawChefError(`Recipe in archive is not a file: ${selector}`);
-      }
-    } catch {
-      throw new ClawChefError(`Recipe file not found in archive: ${selector}`);
-    }
+    const recipePath = await resolveRecipePathFromExtracted(
+      extractDir,
+      selector,
+      `Recipe file not found in archive: ${selector}`,
+    );
     return {
       recipePath,
       origin: {