stageflow 0.33.0 → 0.36.0

package/dist/config/hostConfig.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { globalStageflowHome } from "../project/globalHome.js";
+import { validateProfileScope } from "../browser/profileStore.js";
 import { readSecretFromEnvOrFile } from "./secretFromEnvOrFile.js";
 export class HostConfigError extends Error {
     code;
@@ -16,7 +17,10 @@ export class HostConfigError extends Error {
 /** Env keys that are known STAGEFLOW_* (or dynamic families) so unknown-key check accepts them. */
 export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_HOME",
+    "STAGEFLOW_CREDENTIAL_HOME",
+    "STAGEFLOW_CONNECTIONS_FILE",
     "STAGEFLOW_BIND",
+    "STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND",
     "STAGEFLOW_ALLOWED_HOSTS",
     "STAGEFLOW_CONTROL_TOKEN",
     "STAGEFLOW_CONTROL_TOKEN_FILE",
@@ -40,6 +44,7 @@ export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_LOG_MAX_LINE_BYTES",
     "STAGEFLOW_MCP_STATELESS",
     "STAGEFLOW_DISK_WARN_BYTES",
+    "STAGEFLOW_ENSURE_PROJECT_ROOTS",
     "STAGEFLOW_MIN_FREE_DISK_BYTES",
     "STAGEFLOW_BARE_CACHE_TTL_MS",
     "STAGEFLOW_SLIM_ARTIFACT_MAX_BYTES",
@@ -82,6 +87,11 @@ const FILE_KEY_TO_FIELD = {
     callers: "callers",
     browser: "browser",
 };
+export const DEFAULT_BROWSER_DIALOG_TIMEOUT_SECONDS = 60;
+export const DEFAULT_BROWSER_CONTAINER_IMAGE = "stageflow-browser-sandbox:local";
+export function browserHostForOwner(config, scope) {
+    return config.browserOwnerHosts[scope] ?? config.browserHost;
+}
 const DEFAULT_MAX_CONCURRENT = 3;
 const DEFAULT_MAX_QUEUED = 32;
 function isKnownStageflowEnvKey(key) {
@@ -303,16 +313,113 @@ export function loadHostConfig(options) {
         callers = coerceCallers(file.values.callers, "callers");
     }
     let browserBlockedSites = [];
+    let browserLaunchArgs = [];
+    let browserExecutablePath;
+    let browserDialogTimeoutSeconds = DEFAULT_BROWSER_DIALOG_TIMEOUT_SECONDS;
+    let browserHost = "local";
+    const browserOwnerHosts = {};
+    const browserContainer = {
+        image: DEFAULT_BROWSER_CONTAINER_IMAGE,
+        shmSize: "1g",
+        memory: "1g",
+        pidsLimit: 512,
+    };
     if (file.values.browser !== undefined) {
         const raw = file.values.browser;
         if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
             throw new HostConfigError(`Invalid value for browser`, "config_invalid", "browser");
         }
         for (const sub of Object.keys(raw)) {
-            if (sub !== "blocked_sites") {
+            if (sub !== "blocked_sites" && sub !== "launch_args" && sub !== "executable_path" && sub !== "dialog_timeout_seconds" && sub !== "host" && sub !== "container" && sub !== "owner_hosts") {
                 throw new HostConfigError(`Unknown key "${sub}" under browser`, "config_unknown_key", `browser.${sub}`);
             }
         }
+        const args = raw.launch_args;
+        if (args !== undefined && args !== null) {
+            if (!Array.isArray(args) || !args.every((a) => typeof a === "string")) {
+                throw new HostConfigError("Invalid value for browser.launch_args; expected a list of strings", "config_invalid", "browser.launch_args");
+            }
+            for (const arg of args) {
+                if (arg.trim() === "" || /[,\r\n]/.test(arg)) {
+                    throw new HostConfigError(`Invalid item ${JSON.stringify(arg)} in browser.launch_args; each item must be non-empty with no comma or newline`, "config_invalid", "browser.launch_args");
+                }
+            }
+            browserLaunchArgs = args.map((a) => a.trim());
+        }
+        const exe = raw.executable_path;
+        if (exe !== undefined && exe !== null) {
+            if (typeof exe !== "string" ||
+                exe.trim() === "" ||
+                !(path.posix.isAbsolute(exe.trim()) || path.win32.isAbsolute(exe.trim()))) {
+                throw new HostConfigError("Invalid value for browser.executable_path; expected a non-empty absolute path", "config_invalid", "browser.executable_path");
+            }
+            browserExecutablePath = exe.trim();
+        }
+        const dialogTimeout = raw.dialog_timeout_seconds;
+        if (dialogTimeout !== undefined && dialogTimeout !== null) {
+            if (typeof dialogTimeout !== "number" ||
+                !Number.isInteger(dialogTimeout) ||
+                dialogTimeout < 1) {
+                throw new HostConfigError("Invalid value for browser.dialog_timeout_seconds; expected a positive integer", "config_invalid", "browser.dialog_timeout_seconds");
+            }
+            browserDialogTimeoutSeconds = dialogTimeout;
+        }
+        const host = raw.host;
+        if (host !== undefined && host !== null) {
+            if (host !== "local" && host !== "container") {
+                throw new HostConfigError('Invalid value for browser.host; expected "local" or "container"', "config_invalid", "browser.host");
+            }
+            browserHost = host;
+        }
+        const ownerHosts = raw.owner_hosts;
+        if (ownerHosts !== undefined && ownerHosts !== null) {
+            if (typeof ownerHosts !== "object" || Array.isArray(ownerHosts)) {
+                throw new HostConfigError("Invalid value for browser.owner_hosts", "config_invalid", "browser.owner_hosts");
+            }
+            for (const [scope, value] of Object.entries(ownerHosts)) {
+                try {
+                    validateProfileScope(scope);
+                }
+                catch {
+                    throw new HostConfigError(`Invalid owner scope "${scope}" in browser.owner_hosts`, "config_invalid", "browser.owner_hosts");
+                }
+                if (value !== "local" && value !== "container") {
+                    throw new HostConfigError(`Invalid value for browser.owner_hosts.${scope}; expected "local" or "container"`, "config_invalid", `browser.owner_hosts.${scope}`);
+                }
+                browserOwnerHosts[scope] = value;
+            }
+        }
+        const container = raw.container;
+        if (container !== undefined && container !== null) {
+            if (typeof container !== "object" || Array.isArray(container)) {
+                throw new HostConfigError("Invalid value for browser.container", "config_invalid", "browser.container");
+            }
+            const fields = container;
+            for (const sub of Object.keys(fields)) {
+                if (!["image", "shm_size", "memory", "pids_limit"].includes(sub)) {
+                    throw new HostConfigError(`Unknown key "${sub}" under browser.container`, "config_unknown_key", `browser.container.${sub}`);
+                }
+            }
+            const text = (key, pattern, target) => {
+                const value = fields[key];
+                if (value === undefined || value === null)
+                    return;
+                if (typeof value !== "string" || !pattern.test(value.trim())) {
+                    throw new HostConfigError(`Invalid value for browser.container.${key}`, "config_invalid", `browser.container.${key}`);
+                }
+                browserContainer[target] = value.trim();
+            };
+            text("image", /^[A-Za-z0-9][A-Za-z0-9._\-/:@]*$/, "image");
+            text("shm_size", /^[1-9][0-9]*[bkmg]?$/i, "shmSize");
+            text("memory", /^[1-9][0-9]*[bkmg]?$/i, "memory");
+            const pids = fields.pids_limit;
+            if (pids !== undefined && pids !== null) {
+                if (typeof pids !== "number" || !Number.isInteger(pids) || pids < 1) {
+                    throw new HostConfigError("Invalid value for browser.container.pids_limit; expected a positive integer", "config_invalid", "browser.container.pids_limit");
+                }
+                browserContainer.pidsLimit = pids;
+            }
+        }
         const sites = raw.blocked_sites;
         if (sites !== undefined) {
             browserBlockedSites = coerceFileStringList(sites, "browser.blocked_sites")
@@ -336,6 +443,12 @@ export function loadHostConfig(options) {
         readToken,
         callers,
         browserBlockedSites,
+        browserLaunchArgs,
+        browserExecutablePath,
+        browserDialogTimeoutSeconds,
+        browserHost,
+        browserOwnerHosts,
+        browserContainer,
         configFilePath: configFilePath !== undefined && existsSync(configFilePath)
             ? configFilePath
             : undefined,

package/dist/config/importTask.d.ts

@@ -0,0 +1,19 @@
+import { type CreateTaskResult } from "./createTask.js";
+export declare const GITHUB_REPO_PATTERN: RegExp;
+export type ImportTaskInput = {
+    repo: string;
+    number: number;
+    directory: string;
+};
+export type ImportTaskParseError = {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export type IssueFetch = (url: string, init: {
+    headers: Record<string, string>;
+}) => Promise<Response>;
+export declare function parseImportTaskBody(body: unknown): ImportTaskInput | ImportTaskParseError;
+export declare function slugIssueTitle(title: string, issueNumber: number): string;
+export declare function taskIdWithSuffix(baseId: string, suffixNumber: number): string;
+export declare function importTaskFromIssue(rawProjectRoot: string, input: ImportTaskInput, fetchImpl?: IssueFetch): Promise<CreateTaskResult>;

package/dist/config/importTask.js

@@ -0,0 +1,133 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { STAGE_ID_PATTERN } from "./createStage.js";
+import { createTask, findTaskIdCollision, resolveTaskDirectory, validateTaskId, } from "./createTask.js";
+export const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function parseImportTaskBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "Request body must be an object" };
+    }
+    if (typeof body.repo !== "string" || !GITHUB_REPO_PATTERN.test(body.repo)) {
+        return { ok: false, status: 400, error: "repo must be a GitHub owner/repo" };
+    }
+    if (typeof body.number !== "number" || !Number.isInteger(body.number) || body.number <= 0) {
+        return { ok: false, status: 400, error: "number must be a positive integer" };
+    }
+    if (typeof body.directory !== "string" || body.directory.trim().length === 0) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    const directory = body.directory.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    if (directory.length === 0) {
+        return { ok: false, status: 400, error: "directory is required" };
+    }
+    return { repo: body.repo, number: body.number, directory };
+}
+export function slugIssueTitle(title, issueNumber) {
+    const fallback = `issue-${issueNumber}`;
+    let slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/^[^a-z]+/, "")
+        .replace(/^-+|-+$/g, "");
+    if (slug.length > 64) {
+        slug = slug.slice(0, 64).replace(/-+$/g, "");
+    }
+    if (!slug || !STAGE_ID_PATTERN.test(slug))
+        return fallback;
+    return slug;
+}
+export function taskIdWithSuffix(baseId, suffixNumber) {
+    const suffix = `-${suffixNumber}`;
+    let stem = baseId;
+    if (stem.length + suffix.length > 64) {
+        stem = stem.slice(0, 64 - suffix.length).replace(/-+$/g, "");
+    }
+    if (!stem || !STAGE_ID_PATTERN.test(stem))
+        stem = "issue";
+    const candidate = `${stem}${suffix}`;
+    if (candidate.length <= 64 && STAGE_ID_PATTERN.test(candidate))
+        return candidate;
+    return `issue${suffix}`;
+}
+async function allocateTaskId(projectRoot, directory, baseId) {
+    for (let n = 1; n <= 100; n += 1) {
+        const id = n === 1 ? baseId : taskIdWithSuffix(baseId, n);
+        const idError = validateTaskId(id);
+        if (idError)
+            continue;
+        const targetPath = path.join(directory, `${id}.task.yaml`);
+        const collision = await findTaskIdCollision(projectRoot, id, targetPath);
+        if (!collision)
+            return id;
+    }
+    return null;
+}
+function githubHeaders() {
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "stageflow",
+    };
+    const token = process.env.GITHUB_TOKEN;
+    if (typeof token === "string" && token.length > 0) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+export async function importTaskFromIssue(rawProjectRoot, input, fetchImpl = (url, init) => fetch(url, init)) {
+    if (!GITHUB_REPO_PATTERN.test(input.repo)) {
+        return { ok: false, status: 400, error: "repo must be a GitHub owner/repo" };
+    }
+    if (!Number.isInteger(input.number) || input.number <= 0) {
+        return { ok: false, status: 400, error: "number must be a positive integer" };
+    }
+    const projectRoot = await realpath(rawProjectRoot).catch(() => rawProjectRoot);
+    const directory = resolveTaskDirectory(projectRoot, input.directory);
+    if (!directory) {
+        return { ok: false, status: 400, error: "directory must be inside the project root" };
+    }
+    const url = `https://api.github.com/repos/${input.repo}/issues/${input.number}`;
+    let response;
+    try {
+        response = await fetchImpl(url, { headers: githubHeaders() });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 502, error: message };
+    }
+    if (response.status === 404) {
+        return {
+            ok: false,
+            status: 404,
+            error: `GitHub issue not found: ${input.repo}#${input.number}`,
+        };
+    }
+    if (!response.ok) {
+        return { ok: false, status: 502, error: `GitHub request failed (${response.status})` };
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        return { ok: false, status: 502, error: "GitHub response was not JSON" };
+    }
+    if (!isPlainObject(payload) || typeof payload.title !== "string" || payload.title.length === 0) {
+        return { ok: false, status: 502, error: "GitHub issue is missing a title" };
+    }
+    const context = typeof payload.body === "string" ? payload.body : "";
+    const baseId = slugIssueTitle(payload.title, input.number);
+    const id = await allocateTaskId(projectRoot, directory, baseId);
+    if (!id) {
+        return { ok: false, status: 409, error: "Unable to allocate a task id" };
+    }
+    return createTask(projectRoot, {
+        directory: input.directory,
+        id,
+        goal: payload.title,
+        ...(context.length > 0 ? { context } : {}),
+    });
+}

package/dist/config/installSkillRequest.d.ts

@@ -0,0 +1,40 @@
+export type InstallSkillParseError = {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export type ParsedInstallSkillRequest = {
+    command: string;
+};
+export type ParsedSkillsAddCommand = {
+    source: string;
+    skillName?: string;
+};
+export type SkillCloneFn = (cloneUrl: string, destDir: string) => Promise<void>;
+export type InstallSkillFromCommandResult = {
+    ok: true;
+    skill_name: string;
+    dest_path: string;
+    project_root: string;
+} | {
+    ok: false;
+    error: string;
+    doctorFailed?: boolean;
+    status?: 400 | 422;
+};
+export declare function parseSkillsAddCommand(command: string): ParsedSkillsAddCommand | InstallSkillParseError;
+export declare function parseInstallSkillBody(body: unknown): ParsedInstallSkillRequest | InstallSkillParseError;
+export type LocatedSkill = {
+    name: string;
+    root: string;
+};
+export declare function locateSkillDirectory(checkoutRoot: string, skillName?: string): Promise<LocatedSkill>;
+export declare function resolveGitCloneUrl(source: string): string;
+export declare function defaultCloneSkillRepo(cloneUrl: string, destDir: string): Promise<void>;
+export declare function installSkillFromCommand(input: {
+    projectRoot: string;
+    command: string;
+    cloneRepo?: SkillCloneFn;
+}): Promise<InstallSkillFromCommandResult>;
+/** Test helper: build a file: command for a local skill tree. */
+export declare function skillsAddFileCommand(fromPath: string, skillName?: string): string;

package/dist/config/installSkillRequest.js

@@ -0,0 +1,286 @@
+import { access, mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { installProjectSkill, } from "../cli/skillsCommand.js";
+import { runGit } from "../git/exec.js";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function tokenizeCommand(command) {
+    return command.trim().split(/\s+/).filter((part) => part.length > 0);
+}
+export function parseSkillsAddCommand(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, status: 400, error: "command must be a non-empty string" };
+    }
+    const tokens = tokenizeCommand(trimmed);
+    let rest;
+    if (tokens[0] === "npx" && tokens[1] === "skills" && tokens[2] === "add") {
+        rest = tokens.slice(3);
+    }
+    else if (tokens[0] === "skills" && tokens[1] === "add") {
+        rest = tokens.slice(2);
+    }
+    else {
+        return {
+            ok: false,
+            status: 400,
+            error: "command must be 'npx skills add <source> [--skill <name>]' or 'skills add …'",
+        };
+    }
+    let source;
+    let skillName;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--skill") {
+            const value = rest[++i];
+            if (value === undefined || value.length === 0) {
+                return { ok: false, status: 400, error: "missing value for --skill" };
+            }
+            if (value.startsWith("-")) {
+                return { ok: false, status: 400, error: "missing value for --skill" };
+            }
+            skillName = value;
+        }
+        else if (arg.startsWith("-")) {
+            return { ok: false, status: 400, error: `unknown flag: ${arg}` };
+        }
+        else if (source === undefined) {
+            source = arg;
+        }
+        else {
+            return { ok: false, status: 400, error: `unexpected argument: ${arg}` };
+        }
+    }
+    if (source === undefined) {
+        return { ok: false, status: 400, error: "missing skill source after 'add'" };
+    }
+    return {
+        source,
+        ...(skillName !== undefined ? { skillName } : {}),
+    };
+}
+export function parseInstallSkillBody(body) {
+    if (!isPlainObject(body)) {
+        return { ok: false, status: 400, error: "Request body must be an object" };
+    }
+    if (typeof body.command !== "string" || body.command.trim().length === 0) {
+        return { ok: false, status: 400, error: "command must be a non-empty string" };
+    }
+    const parsed = parseSkillsAddCommand(body.command);
+    if ("ok" in parsed) {
+        return parsed;
+    }
+    return { command: body.command.trim() };
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readFrontmatterName(skillMdPath) {
+    try {
+        const raw = await readFile(skillMdPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+        if (!match)
+            return undefined;
+        const nameLine = /^name:\s*(.+)\s*$/m.exec(match[1] ?? "");
+        const value = nameLine?.[1]?.trim();
+        if (value === undefined || value.length === 0)
+            return undefined;
+        return value.replace(/^['"]|['"]$/g, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function locateSkillDirectory(checkoutRoot, skillName) {
+    const candidates = [];
+    const seen = new Set();
+    const pushCandidate = (name, root) => {
+        const key = path.resolve(root);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        candidates.push({ name, root: key });
+    };
+    const rootSkillMd = path.join(checkoutRoot, "SKILL.md");
+    if (await pathExists(rootSkillMd)) {
+        const name = (await readFrontmatterName(rootSkillMd)) ?? path.basename(path.resolve(checkoutRoot));
+        pushCandidate(name, checkoutRoot);
+    }
+    let entries;
+    try {
+        entries = await readdir(checkoutRoot, { withFileTypes: true });
+    }
+    catch {
+        throw new Error("skill source directory not found");
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "skills") {
+            continue;
+        }
+        const skillMd = path.join(checkoutRoot, entry.name, "SKILL.md");
+        if (await pathExists(skillMd)) {
+            pushCandidate(entry.name, path.join(checkoutRoot, entry.name));
+        }
+    }
+    const skillsDir = path.join(checkoutRoot, "skills");
+    try {
+        const skillsStat = await stat(skillsDir);
+        if (skillsStat.isDirectory()) {
+            const skillEntries = await readdir(skillsDir, { withFileTypes: true });
+            for (const entry of skillEntries) {
+                if (!entry.isDirectory())
+                    continue;
+                const skillMd = path.join(skillsDir, entry.name, "SKILL.md");
+                if (await pathExists(skillMd)) {
+                    pushCandidate(entry.name, path.join(skillsDir, entry.name));
+                }
+            }
+        }
+    }
+    catch {
+        // no skills/ directory
+    }
+    if (skillName !== undefined) {
+        const namedPaths = [
+            path.join(checkoutRoot, skillName, "SKILL.md"),
+            path.join(checkoutRoot, "skills", skillName, "SKILL.md"),
+        ];
+        for (const skillMd of namedPaths) {
+            if (await pathExists(skillMd)) {
+                return { name: skillName, root: path.dirname(skillMd) };
+            }
+        }
+        const match = candidates.find((candidate) => candidate.name === skillName);
+        if (match !== undefined) {
+            return match;
+        }
+        throw new Error(`skill "${skillName}" not found in source`);
+    }
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    if (candidates.length === 0) {
+        throw new Error("no SKILL.md found in source");
+    }
+    const names = candidates.map((candidate) => candidate.name).join(", ");
+    throw new Error(`multiple skills found (${names}); pass --skill <name>`);
+}
+export function resolveGitCloneUrl(source) {
+    const githubHttps = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?(?:\/|$)/i.exec(source);
+    if (githubHttps) {
+        return `https://github.com/${githubHttps[1]}/${githubHttps[2]}.git`;
+    }
+    if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(source)) {
+        return `https://github.com/${source}.git`;
+    }
+    throw new Error("source must be a GitHub HTTPS URL, owner/repo slug, or file: URL");
+}
+export async function defaultCloneSkillRepo(cloneUrl, destDir) {
+    await runGit({
+        args: ["clone", "--depth", "1", "--single-branch", cloneUrl, destDir],
+        timeoutMs: 120_000,
+    });
+}
+function resolveFileSource(source) {
+    if (source.startsWith("file:")) {
+        return fileURLToPath(source);
+    }
+    throw new Error("source must be a GitHub HTTPS URL, owner/repo slug, or file: URL");
+}
+export async function installSkillFromCommand(input) {
+    const parsed = parseSkillsAddCommand(input.command);
+    if ("ok" in parsed) {
+        return { ok: false, error: parsed.error, status: parsed.status };
+    }
+    let cleanup;
+    try {
+        let checkoutRoot;
+        if (parsed.source.startsWith("file:")) {
+            checkoutRoot = resolveFileSource(parsed.source);
+            try {
+                const sourceStat = await stat(checkoutRoot);
+                if (!sourceStat.isDirectory()) {
+                    return { ok: false, error: "skill source path not found", status: 400 };
+                }
+            }
+            catch {
+                return { ok: false, error: "skill source path not found", status: 400 };
+            }
+        }
+        else {
+            let cloneUrl;
+            try {
+                cloneUrl = resolveGitCloneUrl(parsed.source);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                    status: 400,
+                };
+            }
+            const tempRoot = await mkdtemp(path.join(tmpdir(), "sf-skill-clone-"));
+            cleanup = async () => {
+                await rm(tempRoot, { recursive: true, force: true });
+            };
+            const cloneDest = path.join(tempRoot, "repo");
+            const cloneRepo = input.cloneRepo ?? defaultCloneSkillRepo;
+            await cloneRepo(cloneUrl, cloneDest);
+            checkoutRoot = cloneDest;
+        }
+        const located = await locateSkillDirectory(checkoutRoot, parsed.skillName);
+        const result = await installProjectSkill({
+            projectRoot: input.projectRoot,
+            fromPath: located.root,
+            skillName: located.name,
+            io: {
+                log: () => undefined,
+                error: () => undefined,
+            },
+        });
+        if (!result.ok) {
+            return {
+                ok: false,
+                error: result.error,
+                ...(result.doctorFailed ? { doctorFailed: true, status: 422 } : { status: 400 }),
+            };
+        }
+        return {
+            ok: true,
+            skill_name: result.skillName,
+            dest_path: result.destPath,
+            project_root: input.projectRoot,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            status: 400,
+        };
+    }
+    finally {
+        if (cleanup !== undefined) {
+            await cleanup();
+        }
+    }
+}
+/** Test helper: build a file: command for a local skill tree. */
+export function skillsAddFileCommand(fromPath, skillName) {
+    const source = pathToFileURL(path.resolve(fromPath)).href;
+    if (skillName === undefined) {
+        return `npx skills add ${source}`;
+    }
+    return `npx skills add ${source} --skill ${skillName}`;
+}