humanish 0.107.0 → 0.109.0

package/dist/tui/launch.js

@@ -1,35 +1,35 @@
-// Starting a run from the terminal surface (#455).
+// Starting a run from the terminal surface.
 //
-// THE RUN MUST OUTLIVE THE SURFACE. A study can take minutes and costs real money, so a run
+// The run must outlive the surface. A study can take minutes and costs real money, so a run
 // started from the TUI cannot be a child of the TUI's event loop: closing the surface, or losing
 // the SSH session it is running over, must not kill it. So this spawns the CLI the same way a
-// person would type it — detached, in its own process group, with its output going to a file
+// person would type it: detached, in its own process group, with its output going to a file
 // rather than to a terminal that may be about to disappear.
 //
 // The surface then learns what happened the same way any other reader does: from `status.json`.
 // It does not hold a handle to the run, parse its stdout, or track it in memory. That is what
-// makes the surface restartable — quit the TUI mid-run, reopen it, and the run is still there,
+// makes the surface restartable: quit the TUI mid-run, reopen it, and the run is still there,
 // because the filesystem was always the source of truth rather than a process handle.
 import { spawn } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
 import { open } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveLabManifest } from "../lab/discover.js";
+import { resolveStudyManifest } from "../study/discover.js";
 import { prepareManagedHumanishOutputDirectory } from "../run/contained-output.js";
 /**
- * A lab handle is the manifest FILENAME, which is what `humanish lab run` resolves. Restricted to
- * characters a manifest name can actually contain, and — the part that matters — never allowed to
- * begin with `-`, because argv is positional: a lab called `--json` would otherwise be handed to
+ * A study handle is the manifest filename, which is what `humanish run` resolves. Restricted to
+ * characters a manifest name can actually contain, and (the part that matters) never allowed to
+ * begin with `-`, because argv is positional: a study called `--json` would otherwise be handed to
  * the CLI as a flag. There is no shell involved, so this is the whole injection surface.
  *
- * A leading underscore IS allowed: `_wip.yaml` is an ordinary way to name a work-in-progress
- * manifest, `humanish lab run _wip` resolves it, and refusing it here would leave the surface
- * listing a lab it will not start. A leading dot stays out — that names a hidden file, not a lab.
+ * A leading underscore is allowed: `_wip.yaml` is an ordinary way to name a work-in-progress
+ * manifest, `humanish run _wip` resolves it, and refusing it here would leave the surface
+ * listing a study it will not start. A leading dot stays out: that names a hidden file, not a study.
  */
-const SAFE_LAB_HANDLE = /^[A-Za-z0-9_][A-Za-z0-9._:-]*$/;
-export function isSafeLabHandle(value) {
-    return SAFE_LAB_HANDLE.test(value) && value.length <= 128;
+const SAFE_STUDY_HANDLE = /^[A-Za-z0-9_][A-Za-z0-9._:-]*$/;
+export function isSafeStudyHandle(value) {
+    return SAFE_STUDY_HANDLE.test(value) && value.length <= 128;
 }
 /** Where the CLI lives, relative to this compiled module. */
 function defaultCliPath() {
@@ -40,28 +40,34 @@ function defaultCliPath() {
  * result the surface can render, not an exception that would tear down the screen.
  */
 export async function launchRun(options) {
-    if (!isSafeLabHandle(options.lab)) {
+    if (!isSafeStudyHandle(options.study)) {
         return {
             ok: false,
             error: {
-                code: "HUMANISH_LAUNCH_INVALID_LAB",
-                message: `"${options.lab}" is not a usable lab handle. Run it by path with \`humanish lab run <path>\` instead.`,
+                code: "HUMANISH_LAUNCH_INVALID_STUDY",
+                message: `"${options.study}" is not a usable study handle. Run it by path with \`humanish run <path>\` instead.`,
             },
         };
     }
     const cwd = path.resolve(options.cwd);
-    let selectedLab = options.lab;
+    let selectedStudy = options.study;
     if (options.manifestPath !== undefined) {
-        const resolved = await resolveLabManifest(cwd, options.manifestPath);
-        if (!resolved.ok)
+        const resolved = await resolveStudyManifest(cwd, options.manifestPath);
+        if (!resolved.ok) {
+            // A file humanish no longer reads gets discovery's message, which names the fix.
+            const named = resolved.error.code === "HUMANISH_STUDY_V2_UNSUPPORTED" ||
+                resolved.error.code === "HUMANISH_STUDY_RETIRED_DIRECTORY";
             return {
                 ok: false,
                 error: {
-                    code: "HUMANISH_LAUNCH_INVALID_LAB",
-                    message: "The selected lab path could not be read safely. Refresh the lab list.",
+                    code: "HUMANISH_LAUNCH_INVALID_STUDY",
+                    message: named
+                        ? resolved.error.message
+                        : "The selected study path could not be read safely. Refresh the study list.",
                 },
             };
-        selectedLab = path.relative(cwd, path.resolve(cwd, resolved.path)).replace(/\\/g, "/");
+        }
+        selectedStudy = path.relative(cwd, path.resolve(cwd, resolved.path)).replace(/\\/g, "/");
     }
     const now = options.now ?? (() => new Date());
     const spawnFn = options.spawn ?? spawn;
@@ -73,9 +79,9 @@ export async function launchRun(options) {
         // symlinked directory cannot redirect the log somewhere outside the project.
         const logDir = await prepareManagedHumanishOutputDirectory(cwd, "launches");
         const stamp = launchedAt.replace(/[:.]/g, "-");
-        logPath = path.join(logDir.physicalPath, `${stamp}-${options.lab}.log`);
-        // O_NOFOLLOW so a symlink planted at this path cannot redirect a run's output — which may carry
-        // provider error text — outside the project, and cannot defeat the 0600 mode by pointing at a
+        logPath = path.join(logDir.physicalPath, `${stamp}-${options.study}.log`);
+        // O_NOFOLLOW so a symlink planted at this path cannot redirect a run's output (which may carry
+        // provider error text) outside the project, and cannot defeat the 0600 mode by pointing at a
         // file that already exists with looser permissions. O_CREAT|O_APPEND keeps ordinary reuse
         // working; only a symlink is refused (ELOOP).
         handle = await open(logPath, fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_NOFOLLOW, 0o600);
@@ -93,7 +99,6 @@ export async function launchRun(options) {
     // the operator's attention and must not have a browser thrown over it.
     const args = [
         options.cliPath ?? defaultCliPath(),
-        "lab",
         "run",
         "--cwd",
         cwd,
@@ -102,7 +107,7 @@ export async function launchRun(options) {
         ...(options.mode === "dry-run" ? ["--dry-run"] : []),
         // `--` ends option parsing, so the handle can only ever be read as the positional argument.
         "--",
-        selectedLab,
+        selectedStudy,
     ];
     const spawnOptions = {
         cwd,
@@ -115,9 +120,9 @@ export async function launchRun(options) {
     };
     try {
         const child = spawnFn(process.execPath, args, spawnOptions);
-        // A spawn failure is delivered ASYNCHRONOUSLY as an 'error' event (EAGAIN, EMFILE, ENOMEM, a
+        // A spawn failure is delivered asynchronously as an 'error' event (EAGAIN, EMFILE, ENOMEM, a
         // vanished node binary). An 'error' event with no listener is re-thrown by EventEmitter as an
-        // uncaught exception — which would tear down the whole surface, the one thing this module
+        // uncaught exception, which would tear down the whole surface, the one thing this module
         // promises never to do. The run is already unref'd and unobserved, so recording it is all that
         // is available; the operator learns about it from the launch log and the missing record.
         child.on("error", () => {
@@ -151,7 +156,7 @@ export async function launchRun(options) {
         };
     }
 }
-/** Read the tail of a launch log — the only account of a run that died before writing evidence. */
+/** Read the tail of a launch log: the only account of a run that died before writing evidence. */
 export async function readLaunchLogTail(logPath, maxBytes = 4_000) {
     try {
         const handle = await open(logPath, "r");

package/dist/tui/project.js

@@ -1,9 +1,9 @@
-// Is this directory a humanish project at all? (#455)
+// Is this directory a humanish project at all?
 //
-// The surface has two very different empty states and used to render one screen for both. A
-// project with no labs yet needs "write one"; a directory that is not a project — someone's home
-// directory, because `npx humanish tui` is easy to type anywhere — needs to know that first. The
-// second is what Daniel hit, and being told "no labs here yet" in `~` reads as a broken tool.
+// The surface has two empty states and renders a different screen for each. A project with no
+// labs yet needs "write one"; a directory that is not a project (someone's home directory,
+// because `npx humanish tui` is easy to type anywhere) needs to know that first. Being told "no
+// labs here yet" in `~` reads as a broken tool.
 import { existsSync } from "node:fs";
 import path from "node:path";
 const TUI_PROJECT_SCHEMA = "humanish.tui-project.v1";