stageflow 0.32.0 → 0.35.0

package/dist/config/ensureCatalogScanRoot.js

@@ -7,13 +7,17 @@ export function normalizeCatalogDir(directory) {
     return directory.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
 }
 /** Untitled workshop saves land here so Run can see them without a new catalog edit. */
-export function defaultWorkshopPackageDirectory(pipelineId) {
+export function defaultWorkshopPackageDirectory(pipelineId, catalogRootKind) {
     const slug = (pipelineId ?? "")
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .slice(0, 40);
-    return `${WORKSHOP_PACKAGE_ROOT}/${slug || "untitled"}`;
+    const id = slug || "untitled";
+    if (catalogRootKind === "workspace") {
+        return id;
+    }
+    return `${WORKSHOP_PACKAGE_ROOT}/${id}`;
 }
 /**
  * Catalog root that covers this package directory.

package/dist/config/findTaskInCatalog.d.ts

@@ -0,0 +1,33 @@
+import type { TaskFile } from "../types/task.js";
+import { type ResolveCatalogRootsOptions } from "./resolveCatalogRoots.js";
+export type TaskDetail = TaskFile & {
+    path: string;
+};
+export type TaskDetailWithRoot = TaskDetail & {
+    project_root: string;
+};
+export type FindTaskInCatalogMultiResult = {
+    ok: true;
+    task: TaskDetailWithRoot;
+} | {
+    ok: false;
+    status: 404;
+    error: string;
+} | {
+    ok: false;
+    status: 400;
+    error: string;
+    code: "unknown_project_root";
+} | {
+    ok: false;
+    status: 409;
+    error: string;
+    code: "ambiguous_task";
+    project_roots: string[];
+};
+export declare function findTaskInProjectRoot(projectRoot: string, taskId: string): Promise<TaskDetail | null>;
+export declare function findTaskInCatalogMulti(options: ResolveCatalogRootsOptions & {
+    taskId: string;
+    projectRootFilter?: string;
+}): Promise<FindTaskInCatalogMultiResult>;
+export declare function findTaskInCatalog(cwd: string, taskId: string): Promise<TaskDetail | null>;

package/dist/config/findTaskInCatalog.js

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { loadTaskOutcome } from "./loadTask.js";
+import { listTasksMultiProject } from "./multiProjectCatalog.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { findCatalogRoot, } from "./resolveCatalogRoots.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+export async function findTaskInProjectRoot(projectRoot, taskId) {
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(projectRoot));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths || ctx.projectRoot === null) {
+        return null;
+    }
+    const root = ctx.projectRoot;
+    for (const filePath of scanPaths.taskPaths) {
+        const outcome = await loadTaskOutcome(filePath);
+        if (!outcome.ok || outcome.value.id !== taskId) {
+            continue;
+        }
+        return {
+            ...outcome.value,
+            path: path.relative(root, filePath).replace(/\\/g, "/"),
+        };
+    }
+    return null;
+}
+export async function findTaskInCatalogMulti(options) {
+    const { taskId, projectRootFilter, ...rootOptions } = options;
+    const listed = await listTasksMultiProject({
+        ...rootOptions,
+        projectRootFilter,
+    });
+    if (projectRootFilter !== undefined &&
+        listed.root_errors.some((e) => e.code === "unknown_project_root")) {
+        return {
+            ok: false,
+            status: 400,
+            error: listed.root_errors[0].message,
+            code: "unknown_project_root",
+        };
+    }
+    const matches = listed.items.filter((t) => t.id === taskId);
+    if (matches.length === 0) {
+        return { ok: false, status: 404, error: `Task not found: ${taskId}` };
+    }
+    const projectRoots = [...new Set(matches.map((m) => m.project_root))];
+    if (projectRoots.length > 1) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Task id is ambiguous across catalog roots: ${taskId}`,
+            code: "ambiguous_task",
+            project_roots: projectRoots.sort((a, b) => a.localeCompare(b)),
+        };
+    }
+    const wireRoot = projectRoots[0];
+    const catalogRoot = findCatalogRoot(listed.roots, wireRoot);
+    if (catalogRoot === undefined) {
+        return { ok: false, status: 404, error: `Task not found: ${taskId}` };
+    }
+    const detail = await findTaskInProjectRoot(catalogRoot.path, taskId);
+    if (!detail) {
+        return { ok: false, status: 404, error: `Task not found: ${taskId}` };
+    }
+    return { ok: true, task: { ...detail, project_root: wireRoot } };
+}
+export async function findTaskInCatalog(cwd, taskId) {
+    return findTaskInProjectRoot(cwd, taskId);
+}

package/dist/config/hostConfig.d.ts

@@ -9,6 +9,14 @@ export declare const KNOWN_STAGEFLOW_ENV_KEYS: Set<string>;
 export type CallerQuotaConfig = {
     maxConcurrent: number;
 };
+export declare const DEFAULT_BROWSER_DIALOG_TIMEOUT_SECONDS = 60;
+export type BrowserContainerConfig = {
+    image: string;
+    shmSize: string;
+    memory: string;
+    pidsLimit: number;
+};
+export declare const DEFAULT_BROWSER_CONTAINER_IMAGE = "stageflow-browser-sandbox:local";
 export type HostConfig = {
     maxConcurrentRuns: number;
     maxConcurrentRunsPerProject: number | undefined;
@@ -22,6 +30,18 @@ export type HostConfig = {
     callers: Record<string, CallerQuotaConfig>;
     /** Domains no browser stage may use (`browser.blocked_sites` in config.yaml). */
     browserBlockedSites: string[];
+    /** Chrome launch arguments (`browser.launch_args`); empty when unset. */
+    browserLaunchArgs: string[];
+    /** Explicit Chrome path (`browser.executable_path`); undefined when unset. */
+    browserExecutablePath: string | undefined;
+    /** Seconds an unanswered live view page dialog waits before the Host dismisses it (`browser.dialog_timeout_seconds`). */
+    browserDialogTimeoutSeconds: number;
+    /** Where shared profile browsers run (`browser.host`): this machine, or one container per run. */
+    browserHost: "local" | "container";
+    /** Per-owner adapter override (`browser.owner_hosts`, owner scope to host); scopes absent here use `browserHost`. */
+    browserOwnerHosts: Record<string, "local" | "container">;
+    /** Container host settings (`browser.container`); defaults apply when unset. */
+    browserContainer: BrowserContainerConfig;
     /** Absolute path of config.yaml when loaded; undefined if absent. */
     configFilePath: string | undefined;
     warnings: string[];
@@ -45,6 +65,7 @@ export type HostConfigPublicEcho = {
     callers: Record<string, CallerQuotaConfig>;
     secrets: HostConfigSecretsEcho;
 };
+export declare function browserHostForOwner(config: Pick<HostConfig, "browserHost" | "browserOwnerHosts">, scope: string): "local" | "container";
 /**
  * Assemble HostConfig once at boot. Precedence: overrides (CLI flags) > env > file > default.
  */

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,9 @@ 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_BIND",
+    "STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND",
     "STAGEFLOW_ALLOWED_HOSTS",
     "STAGEFLOW_CONTROL_TOKEN",
     "STAGEFLOW_CONTROL_TOKEN_FILE",
@@ -40,6 +43,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 +86,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 +312,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 +442,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;