humanish 0.107.0 → 0.109.0

package/dist/{lab → study}/discover.js

@@ -1,92 +1,80 @@
-import { labPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
+import { studyPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
 import { personaBrief, PersonaConfigError } from "./persona.js";
 import { constants } from "node:fs";
 import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { parse } from "yaml";
-import { parseLabConfig } from "./config.js";
-import {} from "./types.js";
+import { parseStudy } from "./config.js";
+import { V2_SCHEMA } from "./types.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 import { isNodeError } from "../run/type-guards.js";
-const LAB_LIST_SCHEMA = "humanish.lab-list.v1";
-const LAB_INSPECT_SCHEMA = "humanish.lab-inspect.v1";
-const committedLabsDir = path.join("humanish", "labs");
-const ignoredLabsDirs = [
-    path.join(".humanish", "labs"),
-    path.join(".humanish", "local", "labs"),
-];
-export async function resolveLabManifest(cwd, lab) {
+import { studyFileCandidates, STUDY_DIRECTORIES } from "./files.js";
+const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
+const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
+export async function resolveStudyManifest(cwd, study) {
     const resolvedCwd = path.resolve(cwd);
     const warnings = [];
     const projectRoot = await bindProjectRoot(resolvedCwd);
     if (!projectRoot) {
-        return invalidLab({ cwd: resolvedCwd, lab, warnings }, "Project root failed containment validation.");
+        return invalidStudy({ cwd: resolvedCwd, study, warnings }, "Project root failed containment validation.");
     }
-    if (labLooksLikePath(lab)) {
-        const requestedPath = path.resolve(resolvedCwd, lab);
+    if (studyLooksLikePath(study)) {
+        const requestedPath = path.resolve(resolvedCwd, study);
         const read = await readExplicitManifest(projectRoot, requestedPath);
         if (read.status === "missing") {
-            return labNotFound(resolvedCwd, lab, warnings);
+            return studyNotFound(resolvedCwd, study, warnings);
         }
         if (read.status === "unsafe") {
-            return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
+            return invalidStudy({ cwd: resolvedCwd, study, warnings }, read.message);
         }
-        return parseResolvedLab({
+        return parseResolvedStudy({
             cwd: resolvedCwd,
-            lab,
+            study,
             origin: "explicit",
             path: requestedPath,
             warnings,
             contents: read.contents,
         });
     }
-    const candidates = [
-        { origin: "committed", relativePath: path.join(committedLabsDir, `${lab}.yaml`) },
-        { origin: "committed", relativePath: path.join(committedLabsDir, `${lab}.yml`) },
-        ...ignoredLabsDirs.flatMap((dir) => [
-            { origin: "ignored", relativePath: path.join(dir, `${lab}.yaml`) },
-            { origin: "ignored", relativePath: path.join(dir, `${lab}.yml`) },
-        ]),
-    ];
-    for (const candidate of candidates) {
-        const requestedPath = path.join(resolvedCwd, candidate.relativePath);
+    // The studies/ directories are read in order. A name found only under a labs/ directory is
+    // refused with what to do about it, so the user is not told the study does not exist.
+    for (const candidate of studyFileCandidates(study)) {
         const read = await readManagedManifest(projectRoot, candidate.relativePath);
         if (read.status === "missing") {
             continue;
         }
         if (read.status === "unsafe") {
-            return invalidLab({ cwd: resolvedCwd, lab, warnings }, read.message);
+            return invalidStudy({ cwd: resolvedCwd, study, warnings }, read.message);
         }
-        return parseResolvedLab({
+        return parseResolvedStudy({
             cwd: resolvedCwd,
-            lab,
-            origin: candidate.origin,
-            path: requestedPath,
+            study,
+            origin: candidate.directory.origin,
+            path: path.join(resolvedCwd, candidate.relativePath),
             warnings,
             contents: read.contents,
+            retiredDirectory: candidate.directory.family === "labs",
         });
     }
-    return labNotFound(resolvedCwd, lab, warnings);
+    return studyNotFound(resolvedCwd, study, warnings);
 }
-export async function listLabManifests(cwd) {
+export async function listStudyManifests(cwd) {
     const resolvedCwd = path.resolve(cwd);
     const warnings = [];
-    const labs = new Map();
+    const retired = [];
+    const listed = new Map();
     const projectRoot = await bindProjectRoot(resolvedCwd);
     if (!projectRoot) {
         return {
-            schema: LAB_LIST_SCHEMA,
+            schema: STUDY_LIST_SCHEMA,
             ok: true,
             cwd: resolvedCwd,
-            labs: [],
-            warnings: ["Project root failed containment validation; managed lab manifests were skipped."],
+            studies: [],
+            retired: [],
+            warnings: ["Project root failed containment validation; study files were skipped."],
         };
     }
-    const dirs = [
-        { origin: "committed", relativeDir: committedLabsDir },
-        ...ignoredLabsDirs.map((relativeDir) => ({ origin: "ignored", relativeDir })),
-    ];
-    for (const entry of dirs) {
+    for (const entry of STUDY_DIRECTORIES) {
         const directory = await bindManagedDirectory(projectRoot, entry.relativeDir);
         if (directory.status === "missing") {
             continue;
@@ -101,39 +89,49 @@ export async function listLabManifests(cwd) {
             await assertManagedDirectoryBinding(projectRoot, entry.relativeDir, directory.binding);
         }
         catch {
-            warnings.push(`${entry.relativeDir}: unsafe managed lab directory; skipped.`);
+            warnings.push(`${entry.relativeDir}: unsafe managed study directory; skipped.`);
             continue;
         }
         for (const name of names.filter((value) => value.endsWith(".yaml") || value.endsWith(".yml"))) {
             let relativePath;
             try {
-                assertSafeOutputPathSegment(name, "Lab manifest name");
+                assertSafeOutputPathSegment(name, "Study file name");
                 relativePath = path.join(entry.relativeDir, name);
             }
             catch {
-                warnings.push(`${entry.relativeDir}: unsafe lab manifest name; skipped.`);
+                warnings.push(`${entry.relativeDir}: unsafe study file name; skipped.`);
                 continue;
             }
             const requestedPath = path.join(resolvedCwd, relativePath);
             const read = await readManagedManifest(projectRoot, relativePath);
             if (read.status !== "ok") {
-                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${read.status === "unsafe" ? read.message : "manifest changed while it was listed; skipped."}`);
+                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${read.status === "unsafe" ? read.message : "study file changed while it was listed; skipped."}`);
                 continue;
             }
-            const parsed = parseResolvedLab({
+            const parsed = parseResolvedStudy({
                 cwd: resolvedCwd,
-                lab: name.replace(/\.(?:ya?ml)$/i, ""),
+                study: name.replace(/\.(?:ya?ml)$/i, ""),
                 origin: entry.origin,
                 path: requestedPath,
                 warnings: [],
                 contents: read.contents,
+                retiredDirectory: entry.family === "labs",
             });
             if (!parsed.ok) {
-                warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${parsed.error.message}`);
+                const { code, message } = parsed.error;
+                if (code === "HUMANISH_STUDY_V2_UNSUPPORTED" ||
+                    code === "HUMANISH_STUDY_RETIRED_DIRECTORY") {
+                    // The message already starts with the file's path.
+                    retired.push({ path: relativeToCwd(resolvedCwd, requestedPath), code, message });
+                    warnings.push(message);
+                }
+                else {
+                    warnings.push(`${relativeToCwd(resolvedCwd, requestedPath)}: ${message}`);
+                }
                 continue;
             }
             const key = `${parsed.config.id}:${entry.origin}:${relativeToCwd(resolvedCwd, requestedPath)}`;
-            labs.set(key, {
+            listed.set(key, {
                 id: parsed.config.id,
                 source: parsed.config.subject.source,
                 origin: entry.origin,
@@ -147,71 +145,76 @@ export async function listLabManifests(cwd) {
         }
     }
     return {
-        schema: LAB_LIST_SCHEMA,
+        schema: STUDY_LIST_SCHEMA,
         ok: true,
         cwd: resolvedCwd,
-        labs: [...labs.values()].sort((left, right) => `${left.origin}:${left.id}`.localeCompare(`${right.origin}:${right.id}`)),
+        studies: [...listed.values()].sort((left, right) => `${left.origin}:${left.id}`.localeCompare(`${right.origin}:${right.id}`)),
+        retired,
         warnings,
     };
 }
-export async function inspectLabManifest(cwd, lab) {
-    const resolved = await resolveLabManifest(cwd, lab);
+export async function inspectStudyManifest(cwd, study) {
+    const resolved = await resolveStudyManifest(cwd, study);
     if (!resolved.ok) {
         return {
-            schema: LAB_INSPECT_SCHEMA,
+            schema: STUDY_SHOW_SCHEMA,
             ok: false,
             cwd: resolved.cwd,
-            lab,
+            study,
             error: resolved.error,
             warnings: resolved.warnings,
         };
     }
     let personaResolution;
     try {
-        personaResolution = await resolveCommittedPersonasForCwd(cwd, labPersonaIds(resolved.config));
+        personaResolution = await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config));
     }
     catch (error) {
         if (!(error instanceof PersonaConfigError))
             throw error;
         return {
-            schema: LAB_INSPECT_SCHEMA,
+            schema: STUDY_SHOW_SCHEMA,
             ok: false,
             cwd: path.resolve(cwd),
-            lab,
-            error: { code: "HUMANISH_LAB_INVALID", message: error.message },
+            study,
+            error: { code: "HUMANISH_STUDY_INVALID", message: error.message },
             warnings: resolved.warnings,
         };
     }
     return {
-        schema: LAB_INSPECT_SCHEMA,
-        personas: labPersonaIds(resolved.config).map((id) => {
+        schema: STUDY_SHOW_SCHEMA,
+        personas: studyPersonaIds(resolved.config).map((id) => {
             const persona = personaResolution.personas.get(id);
             return { id, resolved: !!persona, ...(persona ? { brief: personaBrief(persona) } : {}) };
         }),
         ok: true,
         cwd: path.resolve(cwd),
-        lab,
+        study,
         config: resolved.config,
         origin: resolved.origin,
         path: resolved.path,
         warnings: [...resolved.warnings, ...personaResolution.warnings],
     };
 }
-function parseResolvedLab(args) {
+function parseResolvedStudy(args) {
     let raw;
     try {
         raw = parse(args.contents);
     }
     catch (error) {
-        return invalidLab(args, error instanceof Error ? error.message : "Lab YAML could not be parsed.");
+        return invalidStudy(args, error instanceof Error ? error.message : "The study file's YAML could not be parsed.");
+    }
+    const refusal = retiredStudyRefusal(relativeToCwd(args.cwd, args.path).replace(/\\/g, "/"), raw, args.retiredDirectory === true);
+    if (refusal !== undefined) {
+        return { ok: false, cwd: args.cwd, study: args.study, error: refusal, warnings: args.warnings };
     }
-    const parsed = parseLabConfig(raw);
+    const parsed = parseStudy(raw);
     if (!parsed.ok) {
-        return invalidLab(args, parsed.error.message);
+        return invalidStudy(args, parsed.error.message);
     }
     const warnings = [...args.warnings, ...parsed.warnings];
     if (args.path.endsWith(".yml")) {
-        warnings.push("Prefer .yaml for humanish-authored lab source; .yml is accepted for compatibility only.");
+        warnings.push("Prefer .yaml for study files; .yml is accepted for compatibility only.");
     }
     return {
         ok: true,
@@ -221,6 +224,39 @@ function parseResolvedLab(args) {
         warnings,
     };
 }
+/**
+ * Why humanish refuses this file, or undefined. A humanish.lab.v2 file is refused wherever it is,
+ * and `humanish migrate` converts it (and moves it out of a labs/ directory). A v3 file is refused
+ * only when it was found by name in a labs/ directory; an explicit path to it still runs.
+ */
+function retiredStudyRefusal(relativePath, raw, retiredDirectory) {
+    const directory = path.posix.dirname(relativePath);
+    const studies = directory.replace(/labs$/, "studies");
+    // migrate moves a v2 file out of a labs/ directory however the file was named.
+    const inStudies = STUDY_DIRECTORIES.some((entry) => entry.family === "labs" && entry.relativeDir.replace(/\\/g, "/") === directory);
+    // migrate refuses a path outside its --cwd, so a file outside the project gets its own directory.
+    const migrate = path.isAbsolute(relativePath)
+        ? `humanish migrate --cwd ${shellPath(path.dirname(relativePath))} ${shellPath(path.basename(relativePath))}`
+        : `humanish migrate ${shellPath(relativePath)}`;
+    if (typeof raw === "object" && raw !== null && raw.schema === V2_SCHEMA)
+        return {
+            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
+            message: inStudies
+                ? `${relativePath} is a humanish.lab.v2 file in ${directory}/, which humanish no longer reads. Run ${migrate} to convert it and move it to ${studies}/.`
+                : `${relativePath} is a humanish.lab.v2 file, which humanish no longer reads. Run ${migrate} to convert it.`,
+        };
+    if (retiredDirectory)
+        return {
+            code: "HUMANISH_STUDY_RETIRED_DIRECTORY",
+            message: `${relativePath} is in ${directory}/, which humanish no longer reads. Move it to ${studies}/.`,
+        };
+    return undefined;
+}
+/** A path as one shell argument: quoted when the shell would split or expand it, never an option. */
+function shellPath(value) {
+    const arg = value.startsWith("-") ? `./${value}` : value;
+    return /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`;
+}
 async function bindProjectRoot(cwd) {
     try {
         const lexical = await lstat(cwd);
@@ -242,7 +278,7 @@ async function readManagedManifest(projectRoot, relativePath) {
     if (!contents) {
         return {
             status: "unsafe",
-            message: "Managed lab manifest changed or failed containment validation.",
+            message: "The study file changed or failed containment validation.",
         };
     }
     return { status: "ok", contents: contents.toString("utf8") };
@@ -264,7 +300,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
         if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n) {
             return {
                 status: "unsafe",
-                message: "Explicit lab manifest must resolve to a single-link regular file.",
+                message: "The study file path must resolve to a single-link regular file.",
             };
         }
         const handle = await open(physicalPath, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -276,7 +312,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
                 opened.ino !== before.ino) {
                 return {
                     status: "unsafe",
-                    message: "Explicit lab manifest changed before it could be read safely.",
+                    message: "The study file changed before it could be read safely.",
                 };
             }
             const contents = await handle.readFile();
@@ -293,7 +329,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
                 after.ino !== before.ino) {
                 return {
                     status: "unsafe",
-                    message: "Explicit lab manifest changed while it was being read.",
+                    message: "The study file changed while it was being read.",
                 };
             }
             return { status: "ok", contents: contents.toString("utf8") };
@@ -303,7 +339,7 @@ async function readExplicitManifest(projectRoot, requestedPath) {
         }
     }
     catch {
-        return { status: "unsafe", message: "Explicit lab manifest failed containment validation." };
+        return { status: "unsafe", message: "The study file path failed containment validation." };
     }
 }
 async function bindManagedDirectory(projectRoot, relativePath) {
@@ -327,7 +363,7 @@ async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
         const segments = relativePath.replace(/\\/g, "/").split("/");
         let current = projectRoot.physicalPath;
         for (const [index, segment] of segments.entries()) {
-            assertSafeOutputPathSegment(segment, "Managed lab path segment");
+            assertSafeOutputPathSegment(segment, "Study file path segment");
             current = path.join(current, segment);
             let stats;
             try {
@@ -341,18 +377,21 @@ async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
             }
             const leaf = index === segments.length - 1;
             if (stats.isSymbolicLink()) {
-                return { status: "unsafe", message: "Managed lab paths must not contain symbolic links." };
+                return {
+                    status: "unsafe",
+                    message: "Study directory paths must not contain symbolic links.",
+                };
             }
             if (!leaf && !stats.isDirectory()) {
-                return { status: "unsafe", message: "Managed lab path parents must be directories." };
+                return { status: "unsafe", message: "Study file path parents must be directories." };
             }
             if (leaf && expectedKind === "directory" && !stats.isDirectory()) {
-                return { status: "unsafe", message: "Managed lab directory has an unsafe file type." };
+                return { status: "unsafe", message: "A study directory has an unsafe file type." };
             }
             if (leaf && expectedKind === "file" && (!stats.isFile() || stats.nlink !== 1n)) {
                 return {
                     status: "unsafe",
-                    message: "Managed lab manifest must be a single-link regular file.",
+                    message: "A study file must be a single-link regular file.",
                 };
             }
             if (leaf) {
@@ -368,7 +407,7 @@ async function inspectManagedPath(projectRoot, relativePath, expectedKind) {
         }
     }
     catch {
-        return { status: "unsafe", message: "Managed lab path failed containment validation." };
+        return { status: "unsafe", message: "A study file path failed containment validation." };
     }
     return { status: "missing" };
 }
@@ -380,39 +419,39 @@ async function assertManagedDirectoryBinding(projectRoot, relativePath, binding)
         current.birthtimeNs !== binding.birthtimeNs ||
         current.dev !== binding.dev ||
         current.ino !== binding.ino) {
-        throw new Error("Managed lab directory identity changed after it was bound.");
+        throw new Error("Managed study directory identity changed after it was bound.");
     }
 }
-function invalidLab(args, message) {
+function invalidStudy(args, message) {
     return {
         ok: false,
         cwd: args.cwd,
-        lab: args.lab,
+        study: args.study,
         error: {
-            code: "HUMANISH_LAB_INVALID",
+            code: "HUMANISH_STUDY_INVALID",
             message,
         },
         warnings: args.warnings,
     };
 }
-function labNotFound(cwd, lab, warnings) {
+function studyNotFound(cwd, study, warnings) {
     return {
         ok: false,
         cwd,
-        lab,
+        study,
         error: {
-            code: "HUMANISH_LAB_NOT_FOUND",
-            message: `Lab not found: ${lab}. Look in humanish/labs/ or pass a .yaml path.`,
+            code: "HUMANISH_STUDY_NOT_FOUND",
+            message: `Study not found: ${study}. Look in humanish/studies/, or pass a .yaml path.`,
         },
         warnings,
     };
 }
-function labLooksLikePath(lab) {
-    return (lab.endsWith(".yaml") ||
-        lab.endsWith(".yml") ||
-        lab.includes("/") ||
-        lab.includes("\\") ||
-        lab.startsWith("."));
+function studyLooksLikePath(study) {
+    return (study.endsWith(".yaml") ||
+        study.endsWith(".yml") ||
+        study.includes("/") ||
+        study.includes("\\") ||
+        study.startsWith("."));
 }
 function relativeToCwd(cwd, filePath) {
     const relative = path.relative(cwd, filePath);

package/dist/{lab → study}/doctor.d.ts

@@ -1,12 +1,12 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
-import type { LabConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 import type { PlanResult } from "./plan-types.js";
 import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
-import type { DoctorResult } from "../cli/doctor.js";
-import { type CodexInstallation } from "../actors/codex/qualified-versions.js";
+import type { DoctorCheckDraft } from "../cli/doctor.js";
+import { type CodexInstallation } from "../actors/codex/codex-admission.js";
 import type { RefusedCodexExecutable } from "../actors/codex/restricted-executable.js";
-type Check = DoctorResult["checks"][number];
+type Check = DoctorCheckDraft;
 /**
  * Read-only Codex account readiness. An unadmitted CLI also reports the release it found, and an
  * unavailable one the file humanish found and turned down.
@@ -31,7 +31,7 @@ type HostedCodexReadiness = CodexReadiness & {
 };
 /**
  * The hosted participant check: the operator-auth launch to an ephemeral thread, with no turn,
- * using the lab's declared model and reasoning effort as a run would.
+ * using the study's declared model and reasoning effort as a run would.
  */
 declare function hostedCodexReadiness(env: NodeJS.ProcessEnv, actor: {
     model?: string;
@@ -42,9 +42,9 @@ export declare function localCodexParticipantCheck(args: {
     env: NodeJS.ProcessEnv;
     readiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
 }): Promise<Check>;
-export interface LabSetupCheckArgs {
+export interface StudySetupCheckArgs {
     cwd: string;
-    lab: string;
+    study: string;
     env: NodeJS.ProcessEnv;
     agents: DetectedLocalAgent[];
     keyPresent: (name: string) => boolean;
@@ -56,19 +56,26 @@ export interface LabSetupCheckArgs {
 }
 /**
  * Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network.
- * `keys` are the keys a live run requires. `reads` are the provider keys the lab is known to read,
- * required or not; it is undefined when that is unknown: the lab does not plan, or a declared
+ * `keys` are the keys a live run requires. `reads` are the provider keys the study is known to read,
+ * required or not; it is undefined when that is unknown: the study does not plan, or a declared
  * scorer's host code may read any key.
  */
-export declare function labSetupChecks(args: LabSetupCheckArgs): Promise<{
+export declare function studySetupChecks(args: StudySetupCheckArgs): Promise<{
     desktop: boolean;
     keys: string[];
     reads?: ReadonlySet<string>;
     checks: Check[];
 }>;
 /**
- * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * The ids of the project's labs that need each provider key for a live run, from the same plan
+ * `doctor --study` reads. Each listed manifest resolves by its path, since a file name need not match
+ * the id inside. A study that runs dry, that the plain CLI cannot run, or that does not plan needs
+ * none.
+ */
+export declare function studiesByRequiredKey(cwd: string, keyPresent: (name: string) => boolean): Promise<Map<string, string[]>>;
+/**
+ * The study planned with no run options, so its own scenario mode decides dry or live. Doctor and the
  * TUI read a live run's keys and subject env from this plan's requirements.
  */
-export declare function planCliRun(config: LabConfig, cwd: string): Promise<PlanResult>;
+export declare function planCliRun(config: StudyConfig, cwd: string): Promise<PlanResult>;
 export {};