screenci 0.0.63 → 0.0.64

package/README.md

@@ -15,23 +15,27 @@ npm init screenci@latest
 pnpm create screenci
 ```
 
-`init` creates a ready-to-run project in the current directory, installs
-dependencies, and installs Chromium by default. When using `npm init`, pass
+`init` creates a ready-to-run, self-contained `screenci/` directory ("the
+island") with its own dependencies, and installs Chromium by default. The
+island is deliberately isolated from any surrounding workspace, which makes
+installation reliable inside complex monorepos. When using `npm init`, pass
 extra initializer flags after `--`, for example
 `npm init screenci@latest -- --yes --package-manager pnpm`.
 
 ```text
-screenci.config.ts
-package.json
-tsconfig.json
-README.md
-.gitignore
-.env
-videos/
-  example.video.ts
-.github/workflows/screenci.yaml
+screenci/
+  screenci.config.ts
+  package.json
+  package-lock.json        # or pnpm-lock.yaml / yarn.lock
+  .gitignore
+  videos/
+    example.video.ts
+.github/workflows/screenci.yaml   # at the repo root, scoped to screenci/
 ```
 
+`screenci test` and `screenci record` work both from inside `screenci/` and
+from the repository root.
+
 Docs:
 
 - Getting started: `https://screenci.com/docs`
@@ -92,12 +96,16 @@ Playwright without starting the final recording and upload path.
 npx screenci record
 ```
 
-On the first run without `SCREENCI_SECRET`, `record` prints a one-time ScreenCI
-link, waits for you to finish sign-in in the browser, saves the secret into the
-project env file, and then continues. Pending auth state is cached in
-`.screenci/link-session.json`, so rerunning `record` reuses the same link until
-it expires or completes. Recorded artifacts still live in
-`.screenci/<video-name>/`.
+On the first run without `SCREENCI_SECRET` in an interactive terminal, `record`
+prints a one-time ScreenCI link, waits for you to finish sign-in in the browser,
+saves the secret into the project env file, and then continues. In a
+non-interactive session (no terminal, or `SCREENCI_NONINTERACTIVE=1`) `record`
+does not wait: it prints the sign-in link and exits, so you can open the link,
+sign in, choose a plan, and rerun `record`, which then detects the completed
+session and continues. Set `SCREENCI_SECRET` ahead of time to skip sign-in
+entirely. Pending auth state is cached in `.screenci/link-session.json`, so
+rerunning `record` reuses the same link until it expires or completes. Recorded
+artifacts still live in `.screenci/<video-name>/`.
 
 ## Configure
 

package/dist/cli.d.ts

@@ -8,6 +8,20 @@ type PlaywrightListReportSuite = {
     }>;
     suites?: PlaywrightListReportSuite[];
 };
+/**
+ * Reports whether the current session can complete an interactive browser
+ * sign-in. A session is interactive only when both stdin and stdout are
+ * attached to a terminal and no signal marks the run as automated. This is the
+ * proxy for "a human is present to open the sign-in link" — it does not attempt
+ * to identify any particular caller (CI, a piped shell, or an automated tool).
+ *
+ * Dependency-injected so tests can force a value without a real terminal.
+ */
+export declare function detectInteractiveSession(env?: NodeJS.ProcessEnv, stdout?: {
+    isTTY?: boolean;
+}, stdin?: {
+    isTTY?: boolean;
+}): boolean;
 export declare function collectPlaywrightListTitles(suites: readonly PlaywrightListReportSuite[]): string[];
 type PreparedUploadAsset = {
     fileHash: string;
@@ -66,7 +80,9 @@ export declare function extractConfigStringLiteral(configSource: string, propert
 export declare function extractRecordUploadPolicyLiteral(configSource: string): RecordUploadPolicy | undefined;
 export declare function extractMockRecordLiteral(configSource: string): boolean | undefined;
 export declare function getConfigModuleSpecifier(resolvedConfigPath: string): string;
-export declare function ensureScreenciSecret(resolvedConfigPath?: string): Promise<string | undefined>;
+export declare function ensureScreenciSecret(resolvedConfigPath?: string, opts?: {
+    interactive?: boolean;
+}): Promise<string | undefined>;
 export declare function main(): Promise<void>;
 export declare function logCliError(error: unknown): void;
 export {};

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -36,6 +36,22 @@ function getScreenCIEnvironment() {
     const parsed = parseScreenCIEnvironment(process.env[SCREENCI_ENVIRONMENT_VARIABLE]);
     return parsed ?? 'prod';
 }
+/**
+ * Reports whether the current session can complete an interactive browser
+ * sign-in. A session is interactive only when both stdin and stdout are
+ * attached to a terminal and no signal marks the run as automated. This is the
+ * proxy for "a human is present to open the sign-in link" — it does not attempt
+ * to identify any particular caller (CI, a piped shell, or an automated tool).
+ *
+ * Dependency-injected so tests can force a value without a real terminal.
+ */
+export function detectInteractiveSession(env = process.env, stdout = process.stdout, stdin = process.stdin) {
+    if (env.SCREENCI_NONINTERACTIVE === '1')
+        return false;
+    if (env.CI === 'true')
+        return false;
+    return Boolean(stdout.isTTY) && Boolean(stdin.isTTY);
+}
 export function collectPlaywrightListTitles(suites) {
     const titles = [];
     const visitSuite = (suite) => {
@@ -575,10 +591,27 @@ function resolveWindowsCmdShim(cmd) {
     }
     return shimName;
 }
+function isModuleNotFoundError(error) {
+    return (error instanceof Error &&
+        error.code === 'MODULE_NOT_FOUND');
+}
+function resolvePlaywrightCliEntrypoint(searchFrom) {
+    // Prefer the @playwright/test installed alongside the user's config, since it
+    // is declared as a peer dependency of the project being recorded.
+    try {
+        return require.resolve('@playwright/test/cli', { paths: [searchFrom] });
+    }
+    catch (error) {
+        if (!isModuleNotFoundError(error))
+            throw error;
+    }
+    // Fall back to the copy resolvable from the screenci CLI's own install. This
+    // keeps discovery working when Playwright is hoisted to a parent install or
+    // bundled with the CLI rather than next to the config file.
+    return require.resolve('@playwright/test/cli');
+}
 function resolvePlaywrightSpawnSpec(args, searchFrom) {
-    const cliEntrypoint = require.resolve('@playwright/test/cli', {
-        paths: [searchFrom],
-    });
+    const cliEntrypoint = resolvePlaywrightCliEntrypoint(searchFrom);
     return {
         command: process.execPath,
         args: [cliEntrypoint, ...args],
@@ -662,17 +695,61 @@ function clearRecordingDirectories(dir) {
 function findScreenCIConfig(customPath) {
     if (customPath) {
         const resolvedPath = resolve(process.cwd(), customPath);
-        if (existsSync(resolvedPath)) {
-            return resolvedPath;
+        return existsSync(resolvedPath)
+            ? { kind: 'found', path: resolvedPath }
+            : { kind: 'not-found' };
+    }
+    // Walk up from the current directory looking for a flat `screenci.config.ts`,
+    // which is what's present when the command runs from inside the `screenci/`
+    // island. We deliberately do NOT auto-use a nested
+    // `screenci/screenci.config.ts`: running the CLI from outside the island
+    // resolves the `screenci` binary from the registry (npx download) rather than
+    // the version-pinned island install, so it would silently run a different
+    // version. Instead we detect the island and ask the user to `cd` into it.
+    let current = process.cwd();
+    let islandConfigPath;
+    while (true) {
+        const flatConfig = resolve(current, 'screenci.config.ts');
+        if (existsSync(flatConfig)) {
+            return { kind: 'found', path: flatConfig };
+        }
+        if (islandConfigPath === undefined) {
+            const islandConfig = resolve(current, 'screenci', 'screenci.config.ts');
+            if (existsSync(islandConfig)) {
+                islandConfigPath = islandConfig;
+            }
         }
-        return null;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
     }
-    const cwd = process.cwd();
-    const configPath = resolve(cwd, 'screenci.config.ts');
-    if (existsSync(configPath)) {
-        return configPath;
+    if (islandConfigPath !== undefined) {
+        return { kind: 'island-not-entered', islandConfigPath };
+    }
+    return { kind: 'not-found' };
+}
+// Resolve the config path, or log a helpful message and exit. Centralizes the
+// `cd screenci` guidance so every command (test/record/info/...) behaves the
+// same when invoked from outside the island.
+function resolveScreenCIConfigPathOrExit(customPath) {
+    const resolution = findScreenCIConfig(customPath);
+    switch (resolution.kind) {
+        case 'found':
+            return resolution.path;
+        case 'island-not-entered': {
+            const islandDir = dirname(resolution.islandConfigPath);
+            const relDir = pathRelative(process.cwd(), islandDir) || '.';
+            logger.error(`Error: no screenci.config.ts found here, but found ${pc.cyan(`${relDir}/screenci.config.ts`)}. Run ${pc.cyan(`cd ${relDir}`)} and rerun the command from there.`);
+            return process.exit(1);
+        }
+        case 'not-found': {
+            logger.error(customPath
+                ? `Error: Config file not found: ${customPath}`
+                : 'Error: screenci.config.ts not found in the current directory or any parent.');
+            return process.exit(1);
+        }
     }
-    return null;
 }
 async function hashFile(filePath) {
     return new Promise((resolveHash, reject) => {
@@ -1135,14 +1212,7 @@ async function writeGitHubProjectOutput(projectUrl) {
     await appendFile(githubOutput, `screenci_project_url=${projectUrl}\n`);
 }
 async function loadScreenCIConfigAndEnv(configPath) {
-    const resolvedConfigPath = findScreenCIConfig(configPath);
-    if (!resolvedConfigPath) {
-        const errorMsg = configPath
-            ? `Error: Config file not found: ${configPath}`
-            : 'Error: screenci.config.ts not found in current directory';
-        logger.error(errorMsg);
-        process.exit(1);
-    }
+    const resolvedConfigPath = resolveScreenCIConfigPathOrExit(configPath);
     let screenciConfig;
     try {
         screenciConfig =
@@ -1334,11 +1404,16 @@ async function loadRecordConfigWithoutPlaywrightCollision(resolvedConfigPath) {
         throw err;
     }
 }
-async function requireScreenCISecret(configPath) {
+async function requireScreenCISecret(configPath, opts = {}) {
     const { resolvedConfigPath, screenciConfig } = await loadScreenCIConfigAndEnv(configPath);
     const secret = process.env.SCREENCI_SECRET ??
-        (await ensureScreenciSecret(resolvedConfigPath));
+        (await ensureScreenciSecret(resolvedConfigPath, opts));
     if (!secret) {
+        // In a non-interactive session ensureScreenciSecret already printed the
+        // sign-in link and the next step, so we exit without repeating guidance.
+        if (opts.interactive === false) {
+            process.exit(1);
+        }
         const envFilePath = await resolveProjectEnvFilePath(resolvedConfigPath);
         logger.error(`No SCREENCI_SECRET configured. Rerun ${pc.cyan(getSuggestedScreenciCommand('record'))} or add SCREENCI_SECRET manually to ${envFilePath} by following the guide at ${pc.cyan(SCREENCI_RECORD_DOCS_URL)}.`);
         process.exit(1);
@@ -1351,7 +1426,7 @@ async function requireScreenCISecret(configPath) {
     };
 }
 async function fetchProjectInfo(configPath) {
-    const { screenciConfig, secret, apiUrl } = await requireScreenCISecret(configPath);
+    const { screenciConfig, secret, apiUrl } = await requireScreenCISecret(configPath, { interactive: detectInteractiveSession() });
     const url = new URL(`${apiUrl}/cli/project-info`);
     url.searchParams.set('projectName', screenciConfig.projectName);
     const res = await fetch(url.toString(), {
@@ -1370,7 +1445,9 @@ async function printProjectInfo(configPath) {
     process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
 }
 async function updateVideoVisibility(videoId, isPublic, configPath) {
-    const { secret, apiUrl } = await requireScreenCISecret(configPath);
+    const { secret, apiUrl } = await requireScreenCISecret(configPath, {
+        interactive: detectInteractiveSession(),
+    });
     const method = isPublic ? 'PUT' : 'DELETE';
     const res = await fetch(`${apiUrl}/cli/public-video/${videoId}`, {
         method,
@@ -1461,24 +1538,34 @@ async function createLinkSessionSpec(options) {
         envFilePath: options.envFilePath,
     };
 }
+async function pollLinkSessionOnce(spec) {
+    const response = await fetch(spec.pollUrl);
+    const body = (await response.json());
+    const status = body.status ?? 'invalid';
+    if (status === 'completed' && body.secret) {
+        return { status, secret: body.secret };
+    }
+    if (status === 'pending' && new Date().toISOString() >= spec.expiresAt) {
+        return { status: 'expired' };
+    }
+    return { status };
+}
 async function pollLinkSession(spec) {
     for (;;) {
-        const response = await fetch(spec.pollUrl);
-        const body = (await response.json());
-        const status = body.status ?? 'invalid';
-        if (status === 'completed' && body.secret) {
-            return { status, secret: body.secret };
-        }
-        if (status === 'expired' || status === 'consumed' || status === 'invalid') {
-            return { status };
+        const result = await pollLinkSessionOnce(spec);
+        if (result.status === 'completed' && result.secret) {
+            return result;
         }
-        if (new Date().toISOString() >= spec.expiresAt) {
-            return { status: 'expired' };
+        if (result.status === 'expired' ||
+            result.status === 'consumed' ||
+            result.status === 'invalid') {
+            return result;
         }
         await new Promise((resolveDelay) => setTimeout(resolveDelay, SCREENCI_LINK_SESSION_POLL_INTERVAL_MS));
     }
 }
-export async function ensureScreenciSecret(resolvedConfigPath) {
+export async function ensureScreenciSecret(resolvedConfigPath, opts = {}) {
+    const interactive = opts.interactive ?? true;
     const existingSecret = process.env.SCREENCI_SECRET;
     if (existingSecret)
         return existingSecret;
@@ -1498,7 +1585,7 @@ export async function ensureScreenciSecret(resolvedConfigPath) {
             envFilePath,
             ...(resolvedConfigPath ? { resolvedConfigPath } : {}),
         };
-        for (;;) {
+        const ensureSpec = async () => {
             const storedSpec = await readPersistedLinkSessionSpec(specPath);
             const spec = storedSpec &&
                 isStoredLinkSessionReusable(storedSpec, linkSessionContext)
@@ -1511,14 +1598,44 @@ export async function ensureScreenciSecret(resolvedConfigPath) {
             if (spec !== storedSpec) {
                 await writePersistedLinkSessionSpec(specPath, spec);
             }
+            return spec;
+        };
+        const saveCompletedSecret = async (secret) => {
+            process.env.SCREENCI_SECRET = secret;
+            await persistScreenCISecret(envFilePath, secret);
+            deletePersistedLinkSessionSpec(specPath);
+            logger.info(`Successfully saved SCREENCI_SECRET to ${envFilePath}`);
+            return secret;
+        };
+        if (!interactive) {
+            // Non-interactive sessions cannot complete a browser sign-in here, so we
+            // never block. Reuse or create the persisted session and check its status
+            // once; if a stored session is stale, recreate it and check once more.
+            // When the session is already completed (the sign-in happened between
+            // runs) we pick up the secret; otherwise we print the link and return so
+            // the caller can surface it and rerun later.
+            let spec = await ensureSpec();
+            let result = await pollLinkSessionOnce(spec);
+            if (result.status === 'expired' ||
+                result.status === 'consumed' ||
+                result.status === 'invalid') {
+                deletePersistedLinkSessionSpec(specPath);
+                spec = await ensureSpec();
+                result = await pollLinkSessionOnce(spec);
+            }
+            if (result.status === 'completed' && result.secret) {
+                return await saveCompletedSecret(result.secret);
+            }
+            logger.info(`Sign-in required to record. Open this link to sign in and choose a plan:\n${pc.cyan(spec.appUrl)}\n` +
+                `This session is non-interactive, so sign-in can't complete here. After signing in, rerun ${pc.cyan(getSuggestedScreenciCommand('record'))} to continue.`);
+            return undefined;
+        }
+        for (;;) {
+            const spec = await ensureSpec();
             logger.info(`Open this link to sign in and connect the CLI:\n${pc.cyan(spec.appUrl)}\n`);
             const result = await pollLinkSession(spec);
             if (result.status === 'completed' && result.secret) {
-                process.env.SCREENCI_SECRET = result.secret;
-                await persistScreenCISecret(envFilePath, result.secret);
-                deletePersistedLinkSessionSpec(specPath);
-                logger.info(`Successfully saved SCREENCI_SECRET to ${envFilePath}`);
-                return result.secret;
+                return await saveCompletedSecret(result.secret);
             }
             deletePersistedLinkSessionSpec(specPath);
         }
@@ -1565,9 +1682,12 @@ export async function main() {
         }
         if (process.env.SCREENCI_RECORDING === 'true')
             return;
-        // After recording, upload results to API if configured
-        const resolvedConfigPath = findScreenCIConfig(parsed.configPath);
-        if (resolvedConfigPath) {
+        // After recording, upload results to API if configured. `run` already
+        // resolved the config (or exited), so this best-effort lookup only acts
+        // when a flat config is present in/under the current directory.
+        const resolution = findScreenCIConfig(parsed.configPath);
+        if (resolution.kind === 'found') {
+            const resolvedConfigPath = resolution.path;
             try {
                 const screenciConfig = await loadRecordConfigWithoutPlaywrightCollision(resolvedConfigPath);
                 loadEnvFile(screenciConfig.envFile
@@ -1674,8 +1794,11 @@ export async function main() {
         .action(async () => {
         const parsed = parseConfigCliArgs(getSubcommandArgv('test'));
         let configMockRecord = false;
-        const resolvedConfigPath = findScreenCIConfig(parsed.configPath);
-        if (resolvedConfigPath) {
+        // Best-effort env preload before handing off to `run`, which performs the
+        // authoritative resolution (and emits the `cd screenci` guidance on miss).
+        const resolution = findScreenCIConfig(parsed.configPath);
+        if (resolution.kind === 'found') {
+            const resolvedConfigPath = resolution.path;
             try {
                 const screenciConfig = await loadRecordConfigWithoutPlaywrightCollision(resolvedConfigPath);
                 configMockRecord = screenciConfig.test?.mockRecord ?? false;
@@ -1846,21 +1969,16 @@ function validateArgs(args) {
     }
 }
 async function run(command, additionalArgs, customConfigPath, verbose = false, mockRecord = false) {
-    const configPath = findScreenCIConfig(customConfigPath);
-    if (!configPath) {
-        const errorMsg = customConfigPath
-            ? `Error: Config file not found: ${customConfigPath}`
-            : 'Error: screenci.config.ts not found in current directory';
-        logger.error(errorMsg);
-        process.exit(1);
-    }
+    const configPath = resolveScreenCIConfigPathOrExit(customConfigPath);
     if (command === 'test' || process.env.SCREENCI_RECORDING !== 'true') {
         await loadEnvFileFromConfigSource(configPath, false);
     }
     // Only validate args for record command
     if (command === 'record') {
         if (!process.env.SCREENCI_SECRET) {
-            await requireScreenCISecret(configPath);
+            await requireScreenCISecret(configPath, {
+                interactive: detectInteractiveSession(),
+            });
         }
         validateArgs(additionalArgs);
         const screenciDir = resolve(dirname(configPath), '.screenci');