@reticlehq/init 3.6.0 → 3.7.0

package/dist/detect/dev-script.d.ts

@@ -1,3 +1,4 @@
+import type { InitIo } from '../run-types.js';
 /**
  * Which command starts this project, and should we start it ourselves?
  *
@@ -72,4 +73,20 @@ export declare function desktopLaunch(pkg: unknown): DesktopLaunch | undefined;
 export declare function devCommandFrom(pkg: unknown, packageManagerCommand: string): string | undefined;
 /** The dev script's own command line (`react-router dev`, `vite`), or undefined when there is none. */
 export declare function devScriptBody(pkg: unknown): string | undefined;
+interface ViteConfigDiscovery {
+    config: {
+        path: string;
+        source: string;
+    } | null;
+    /** Paths that may own Vite but cannot safely be selected automatically. */
+    candidates: readonly string[];
+}
+/**
+ * Find the config that a plain-Vite dev script actually loads.
+ *
+ * An explicit `--config` is authoritative. A direct `vite` command without one keeps Vite's own
+ * root lookup. A custom server with no root config but nested ones is ambiguous, so it returns
+ * evidence for a precise MANUAL step instead of creating a root config the server may never read.
+ */
+export declare function discoverPlainViteConfig(io: InitIo, pkg: unknown, rootFiles: ReadonlySet<string>, configNames: readonly string[]): ViteConfigDiscovery;
 export {};

package/dist/detect/dev-script.js

@@ -137,3 +137,131 @@ export function devScriptBody(pkg) {
     const body = name === undefined ? undefined : table[name];
     return 'string' === typeof body ? body : undefined;
 }
+const SHELL_TOKEN = /"(?:\\.|[^"\\])*"|'[^']*'|&&|\|\||[;|]|[^\s;&|]+/g;
+const SHELL_SEPARATORS = new Set(['&&', '||', ';', '|']);
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const MAX_CONFIG_DEPTH = 4;
+const MAX_CONFIG_CANDIDATES = 20;
+const SKIP_CONFIG_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'out',
+    'coverage',
+    'target',
+    '.git',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+]);
+function unquote(token) {
+    if (token.startsWith("'") && token.endsWith("'"))
+        return token.slice(1, -1);
+    if (token.startsWith('"') && token.endsWith('"')) {
+        return token.slice(1, -1).replace(/\\(["\\])/g, '$1');
+    }
+    return token;
+}
+function safeRelativePath(value) {
+    const normal = unquote(value).replace(/\\/g, '/').replace(/^\.\//, '');
+    if ('' === normal ||
+        normal.startsWith('/') ||
+        normal.startsWith('~') ||
+        /^[A-Za-z]:\//.test(normal) ||
+        normal.split('/').includes('..') ||
+        /[\0$`]/.test(normal)) {
+        return null;
+    }
+    return normal;
+}
+function isViteCommand(token) {
+    const normal = token.replace(/\\/g, '/');
+    return 'vite' === normal || 'vite.cmd' === normal || normal.endsWith('/node_modules/.bin/vite');
+}
+/** The direct Vite invocation in the selected dev script, if that script has one. */
+function viteInvocation(script) {
+    const tokens = script.match(SHELL_TOKEN) ?? [];
+    let start = 0;
+    while (start < tokens.length) {
+        let end = start;
+        while (end < tokens.length && !SHELL_SEPARATORS.has(tokens[end] ?? ''))
+            end += 1;
+        const segment = tokens.slice(start, end).map(unquote);
+        let command = 0;
+        while (command < segment.length && ENV_ASSIGNMENT.test(segment[command] ?? ''))
+            command += 1;
+        if (isViteCommand(segment[command] ?? '')) {
+            const args = segment.slice(command + 1);
+            for (let i = 0; i < args.length; i += 1) {
+                const arg = args[i] ?? '';
+                const inline = /^(?:--config|-c)=(.*)$/.exec(arg);
+                const raw = inline?.[1] ?? ('--config' === arg || '-c' === arg ? args[i + 1] : undefined);
+                if (raw !== undefined) {
+                    return { configArgument: raw, configPath: safeRelativePath(raw) };
+                }
+            }
+            return { configArgument: null, configPath: null };
+        }
+        start = end + 1;
+    }
+    return undefined;
+}
+function nestedViteConfigs(io, configNames) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (found.length >= MAX_CONFIG_CANDIDATES || depth > MAX_CONFIG_DEPTH)
+            return;
+        for (const file of io.listFiles(dir)) {
+            if (configNames.includes(file))
+                found.push(`${dir}/${file}`);
+            if (found.length >= MAX_CONFIG_CANDIDATES)
+                return;
+        }
+        for (const child of io.listDirs(dir)) {
+            if (found.length >= MAX_CONFIG_CANDIDATES)
+                return;
+            if (child.startsWith('.') || SKIP_CONFIG_DIRS.has(child))
+                continue;
+            walk(`${dir}/${child}`, depth + 1);
+        }
+    };
+    for (const dir of io.listDirs('.')) {
+        if (found.length >= MAX_CONFIG_CANDIDATES)
+            break;
+        if (dir.startsWith('.') || SKIP_CONFIG_DIRS.has(dir))
+            continue;
+        walk(dir, 1);
+    }
+    return [...new Set(found)];
+}
+function readable(io, path) {
+    if (null === path)
+        return null;
+    const source = io.readFile(path);
+    return null === source ? null : { path, source };
+}
+/**
+ * Find the config that a plain-Vite dev script actually loads.
+ *
+ * An explicit `--config` is authoritative. A direct `vite` command without one keeps Vite's own
+ * root lookup. A custom server with no root config but nested ones is ambiguous, so it returns
+ * evidence for a precise MANUAL step instead of creating a root config the server may never read.
+ */
+export function discoverPlainViteConfig(io, pkg, rootFiles, configNames) {
+    const rootPath = configNames.find((path) => rootFiles.has(path)) ?? null;
+    const script = devScriptBody(pkg);
+    const invocation = script === undefined ? undefined : viteInvocation(script);
+    if (invocation !== undefined && invocation.configArgument !== null) {
+        const config = readable(io, invocation.configPath);
+        return {
+            config,
+            candidates: null === config ? [invocation.configArgument] : [],
+        };
+    }
+    if (invocation !== undefined)
+        return { config: readable(io, rootPath), candidates: [] };
+    const nested = script === undefined ? [] : nestedViteConfigs(io, configNames);
+    if (null === rootPath && nested.length > 0) {
+        return { config: null, candidates: nested };
+    }
+    return { config: readable(io, rootPath), candidates: [] };
+}

package/dist/detect/workspace-apps.d.ts

@@ -40,6 +40,15 @@ export declare function isWebApp(dir: string, io: Pick<InitIo, 'exists' | 'readF
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+/**
+ * Apps anywhere below a folder that is not one, for `init` run above its app with no workspace to
+ * say where the app is: a backend + frontend repo, a home folder, a docs site in `site/`.
+ *
+ * Breadth first and bounded (depth and folders read), never into dependencies, build output or
+ * hidden folders, and never below an app it found. Apps with a page win; a bare `index.html` with
+ * no package.json counts only when there is none, as the static page it is.
+ */
+export declare function findAppsBelow(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 /**
  * Every package directory the workspace declares or holds, app-shaped or not.
  *
@@ -61,4 +70,6 @@ export declare function workspacePackageDirs(io: Pick<InitIo, 'readFile' | 'list
  * config into a stranger's root.
  */
 export declare function enclosingWorkspaceRoot(cwd: string, io: Pick<InitIo, 'readFile'>): string | undefined;
+/** The apps of the workspace at `root`, read through an io standing somewhere else in it. */
+export declare function appsAt(root: string, io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 export {};

package/dist/detect/workspace-apps.js

@@ -237,6 +237,61 @@ export function findWorkspaceApps(io) {
     // app is exactly that — so it is demoted, never dropped.
     return [...new Set(found.length > 0 ? found : served)];
 }
+/** Folders the search for an app never enters: dependencies, output, and a home folder's own. */
+const NEVER_SEARCHED = new Set([
+    ...NEVER_A_PACKAGE,
+    'vendor',
+    'venv',
+    '__pycache__',
+    'Library',
+    'Applications',
+    'AppData',
+    'Pictures',
+    'Music',
+    'Movies',
+]);
+/** How deep the search goes: `client/web/app` is three, and nothing real is deeper than four. */
+const SEARCH_DEPTH = 4;
+/** Folders read before the search gives up, so a home folder costs a fraction of a second. */
+const SEARCH_BUDGET = 600;
+/**
+ * Apps anywhere below a folder that is not one, for `init` run above its app with no workspace to
+ * say where the app is: a backend + frontend repo, a home folder, a docs site in `site/`.
+ *
+ * Breadth first and bounded (depth and folders read), never into dependencies, build output or
+ * hidden folders, and never below an app it found. Apps with a page win; a bare `index.html` with
+ * no package.json counts only when there is none, as the static page it is.
+ */
+export function findAppsBelow(io) {
+    const apps = [];
+    const pages = [];
+    let level = io.listDirs('.').filter(searchable);
+    let read = 0;
+    for (let depth = 1; depth <= SEARCH_DEPTH && level.length > 0 && read < SEARCH_BUDGET; depth++) {
+        const next = [];
+        for (const dir of level) {
+            if (++read > SEARCH_BUDGET)
+                break;
+            if (AppSignal.UI === appSignal(dir, io)) {
+                apps.push(dir);
+                continue;
+            }
+            if (!io.exists(`${dir}/${PACKAGE_JSON}`) && io.exists(`${dir}/index.html`)) {
+                pages.push(dir);
+                continue;
+            }
+            next.push(...io
+                .listDirs(dir)
+                .filter(searchable)
+                .map((name) => `${dir}/${name}`));
+        }
+        level = next;
+    }
+    return apps.length > 0 ? apps : pages;
+}
+function searchable(name) {
+    return !name.startsWith('.') && !NEVER_SEARCHED.has(name);
+}
 /**
  * Every package directory the workspace declares or holds, app-shaped or not.
  *
@@ -290,3 +345,11 @@ export function enclosingWorkspaceRoot(cwd, io) {
     }
     return undefined;
 }
+/** The apps of the workspace at `root`, read through an io standing somewhere else in it. */
+export function appsAt(root, io) {
+    return findWorkspaceApps({
+        exists: (p) => io.exists(join(root, p)),
+        readFile: (p) => io.readFile(join(root, p)),
+        listDirs: (p) => io.listDirs(join(root, p)),
+    });
+}

package/dist/detect/workspace-redirect.js

@@ -11,7 +11,7 @@
 import { join } from 'node:path';
 import { detect, Framework } from './detect.js';
 import { detectNonJsEcosystem, noPackageJsonMessage } from './non-js-project.js';
-import { findWorkspaceApps, PACKAGE_JSON, workspacePackageDirs } from './workspace-apps.js';
+import { findAppsBelow, findWorkspaceApps, PACKAGE_JSON, workspacePackageDirs, } from './workspace-apps.js';
 import { projectIdOf, RETICLE_CONFIG_FILE } from './existing-config.js';
 import { chooseWorkspaceApp, withoutTrailingSlashes } from './declared/app-choice.js';
 const ROOT_CONFIG_LEAD = `This root's ${RETICLE_CONFIG_FILE} names`;
@@ -30,7 +30,28 @@ function appNamedByRootConfig(io) {
     return 1 === named.length ? named[0] : undefined;
 }
 const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` for the one you want:';
+const BELOW_HEADER = 'No app in this folder. Several below it; re-run `reticle init` for the one you want:';
+const HOME_HEADER = 'This is your home folder, so init wires nothing on its own here. Apps found below it; run one:';
+const STATIC_PAGE = 'index.html';
+/** The folder `init` was run in is the person's home: a place to find apps, never to wire one. */
+function inHome(io) {
+    const trim = (p) => withoutTrailingSlashes(p.replace(/\\/g, '/'));
+    return trim(io.cwd()) === trim(io.homeDir());
+}
+/** Print the candidates as commands to paste, and stop: the choice is the person's. */
+function listApps(io, header, apps) {
+    io.print(header);
+    for (const a of apps) {
+        const displayed = displayedWorkspaceAppCommand(a, process.platform);
+        if (displayed.label !== undefined)
+            io.print(`  ${displayed.label}`);
+        io.print(`  ${displayed.command}`);
+    }
+    return { ok: false, applied: 0, manual: apps.length, listedAppsBelow: true };
+}
 const WORKSPACE_APP_COMMAND = 'reticle init --app';
+const ALREADY_WIRED = 'Already wired here:';
+const WIRE_ANOTHER = 'To wire another app:';
 const POWERSHELL_ONLY_LABEL = 'PowerShell only:';
 const PLAIN_SHELL_ARG = /^[A-Za-z0-9_./-]+$/;
 function posixShellArg(arg) {
@@ -88,7 +109,8 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
     const named = options.app === undefined || '' === options.app ? undefined : options.app;
     if (named !== undefined) {
         const wanted = withoutTrailingSlashes(named);
-        if (io.exists(`${wanted}/${PACKAGE_JSON}`))
+        // A plain page is an app too: `init` wires its index.html once it is standing in that folder.
+        if (io.exists(`${wanted}/${PACKAGE_JSON}`) || io.exists(`${wanted}/${STATIC_PAGE}`))
             return enterApp(options, io, wanted, 'Wiring', runInit);
         const inWanted = (file) => io.exists(`${wanted}/${file}`);
         io.print(detectNonJsEcosystem(inWanted) === undefined
@@ -113,18 +135,39 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
         io.print(chosen.message);
         return { ok: false, applied: 0, manual: 1 };
     }
+    // A home folder holds every project the person has; picking one for them is a guess.
+    if (chosen.app === undefined && inHome(io)) {
+        const found = 0 < apps.length ? apps : findAppsBelow(io);
+        return 0 < found.length ? listApps(io, HOME_HEADER, found) : null;
+    }
+    // No app one or two levels down and no manifest here: look deeper before giving up, so a repo
+    // whose web app sits at `client/web/app`, or a bare page in `site/`, is wired rather than refused.
+    if (0 === apps.length && !io.exists(PACKAGE_JSON) && chosen.app === undefined) {
+        const below = findAppsBelow(io);
+        if (1 === below.length && below[0] !== undefined)
+            return enterApp(options, io, below[0], 'No app in this directory — wiring', runInit);
+        if (1 < below.length)
+            return listApps(io, BELOW_HEADER, below);
+    }
     const target = chosen.app ?? (1 === apps.length ? apps[0] : undefined);
     if (target === undefined) {
         if (0 === apps.length)
             return null; // not a workspace — fall through to the normal HTML plan
-        io.print(AMBIGUOUS_HEADER);
-        for (const a of apps) {
+        // Apps already wired answer a re-run here: nothing to do at the root, which is pinned to none.
+        const wired = apps.filter((a) => io.exists(`${a}/${RETICLE_CONFIG_FILE}`));
+        io.print(0 === wired.length ? AMBIGUOUS_HEADER : `${ALREADY_WIRED} ${wired.join(', ')}.`);
+        const rest = apps.filter((a) => !wired.includes(a));
+        if (0 < wired.length && 0 < rest.length)
+            io.print(WIRE_ANOTHER);
+        for (const a of 0 === wired.length ? apps : rest) {
             const displayed = displayedWorkspaceAppCommand(a, process.platform);
             if (displayed.label !== undefined)
                 io.print(`  ${displayed.label}`);
             io.print(`  ${displayed.command}`);
         }
-        return { ok: false, applied: 0, manual: apps.length };
+        return 0 === wired.length
+            ? { ok: false, applied: 0, manual: apps.length }
+            : { ok: true, applied: 0, manual: 0 };
     }
     return enterApp(options, io, target, 'No app in this directory — wiring', runInit);
 }
@@ -146,5 +189,6 @@ function enterApp(options, io, target, lead, runInit) {
         // Where the human is STANDING, kept across the redirect: their agent session runs here, so
         // this is the only place a `/reticle` command file can be found by it.
         agentRoot: options.agentRoot ?? options.cwd,
+        severalApps: true === options.severalApps || 1 < findWorkspaceApps(io).length,
     }, io.scoped(target));
 }

package/dist/diagnose/init-failure.d.ts

@@ -20,6 +20,8 @@ export declare const InitFailure: {
     readonly APP_CONNECTION: "app_connection";
     readonly BRIDGE_OCCUPIED: "bridge_occupied";
     readonly RUNTIME_ERROR: "runtime_error";
+    /** Ctrl-C (or a SIGTERM) during the runtime phase, before it could say how setup went. */
+    readonly INTERRUPTED: "interrupted";
     readonly OTHER: "other";
 };
 export type InitFailure = (typeof InitFailure)[keyof typeof InitFailure];

package/dist/diagnose/init-failure.js

@@ -20,5 +20,7 @@ export const InitFailure = {
     APP_CONNECTION: 'app_connection',
     BRIDGE_OCCUPIED: 'bridge_occupied',
     RUNTIME_ERROR: 'runtime_error',
+    /** Ctrl-C (or a SIGTERM) during the runtime phase, before it could say how setup went. */
+    INTERRUPTED: 'interrupted',
     OTHER: 'other',
 };

package/dist/gather-plan-input.d.ts

@@ -0,0 +1,11 @@
+import type { InitOptions, InitIo } from './run-types.js';
+import { type PlanInput } from './plan/plan.js';
+/**
+ * The directory the human's agent runs in, when it is not the app's directory.
+ *
+ * `undefined` for a single-package repo, which keeps every agent-file path project-relative exactly
+ * as it was — the two roots are the same there, which is why writing them beside the app went
+ * unnoticed until a repo with its app at `src/admin` reported it.
+ */
+export declare function agentRootOf(options: InitOptions): string | undefined;
+export declare function gatherPlanInput(options: InitOptions, io: InitIo, pkg: unknown): PlanInput;