@reticlehq/init 2.14.0

package/dist/workspace-apps.js

@@ -0,0 +1,188 @@
+import { DEV_SCRIPT_NAMES } from './dev-script.js';
+/**
+ * The file names that say what a directory IS, shared by everything that has to ask.
+ *
+ * They lived in run.ts and are read from here now because `findWorkspaceApps` moved and needs them —
+ * one definition, imported in both directions of the question ("is this an app?" and "which app?").
+ */
+export const PACKAGE_JSON = 'package.json';
+const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
+export const VITE_CONFIG_CANDIDATES = [
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'vite.config.mts',
+];
+export const ELECTRON_VITE_CONFIG_CANDIDATES = [
+    'electron.vite.config.ts',
+    'electron.vite.config.js',
+    'electron.vite.config.mjs',
+    'electron.vite.config.mts',
+];
+export const NEXT_CONFIG_CANDIDATES = [
+    'next.config.mjs',
+    'next.config.js',
+    'next.config.ts',
+    'next.config.cjs',
+];
+/**
+ * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ *
+ * This used to be the literal list `['apps', 'packages']`. Measured on a real repo with three Next
+ * apps at `web/`, `admin/` and `space/`, it found none — so the redirect never fired, init ran
+ * against the root, and it reported ✓ for writing `app/reticle-dev.tsx` into a directory Next never
+ * compiles. A ⚠ tells a human to act; a ✓ tells them it is handled.
+ *
+ * A workspace DECLARES its packages, so that declaration is used first and directory names are not
+ * guessed at all. Where nothing is declared, every top-level directory is a better candidate than two
+ * hardcoded ones — filtered by the usual non-source suspects, and still subject to the `looksLikeApp`
+ * check that follows, so a wrong guess here costs a `package.json` read.
+ */
+/** Directories that are never a workspace package, whatever the layout. */
+const NEVER_A_PACKAGE = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'target']);
+/** `packages/*` -> `packages`; `web` -> `web`. The base directory a glob searches. */
+function globBase(pattern) {
+    const base = pattern
+        .split('/')[0]
+        ?.trim()
+        .replace(/^['"]|['"]$/g, '');
+    return base === undefined || '' === base || '.' === base || base.includes('*') ? undefined : base;
+}
+function fromPnpm(yaml) {
+    // A deliberately small reader rather than a YAML dependency: this file is a list of globs, and the
+    // only shape that matters is `- 'pattern'` under `packages:`. A malformed file yields nothing,
+    // which falls through to the top-level scan rather than failing the install.
+    const out = [];
+    let inPackages = false;
+    for (const line of yaml.split('\n')) {
+        if (/^packages\s*:/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages && /^\S/.test(line))
+            break;
+        const item = /^\s*-\s*(.+)$/.exec(line);
+        if (inPackages && item?.[1] !== undefined) {
+            const base = globBase(item[1]);
+            if (base !== undefined)
+                out.push(base);
+        }
+    }
+    return out;
+}
+function fromPkg(workspaces) {
+    const list = Array.isArray(workspaces)
+        ? workspaces
+        : 'object' === typeof workspaces && workspaces !== null
+            ? workspaces.packages
+            : undefined;
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .filter((p) => 'string' === typeof p)
+        .map(globBase)
+        .filter((p) => p !== undefined);
+}
+export function workspaceParents(sources) {
+    const declared = [
+        ...(sources.pnpmWorkspace === undefined ? [] : fromPnpm(sources.pnpmWorkspace)),
+        ...fromPkg(sources.pkgWorkspaces),
+    ];
+    const candidates = declared.length > 0
+        ? declared
+        : (sources.topLevelDirs ?? []).filter((d) => !d.startsWith('.') && !NEVER_A_PACKAGE.has(d));
+    return [...new Set(candidates)];
+}
+/**
+ * Which directories under this workspace are runnable apps.
+ *
+ * Moved here from run.ts, which was over the 1000-line cap and had carried a note saying it was at
+ * its cohesion limit. `library-path-boundary.test.ts` had already written down that this function
+ * "squats in init/ for historical reasons" — it is a general-purpose question about a repository's
+ * shape, next to `workspaceParents`, which answers the other half of it.
+ */
+/** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
+export const APP_DEPS = ['next', 'vite', 'electron-vite'];
+function hasDevScript(pkgRaw) {
+    try {
+        const parsed = JSON.parse(pkgRaw);
+        const scripts = 'object' === typeof parsed && parsed !== null
+            ? parsed.scripts
+            : undefined;
+        if ('object' !== typeof scripts || null === scripts)
+            return false;
+        const named = scripts;
+        return DEV_SCRIPT_NAMES.some((n) => 'string' === typeof named[n] && '' !== named[n]);
+    }
+    catch {
+        // A manifest that will not parse says nothing either way, and this is a filter, not a verdict.
+        return false;
+    }
+}
+function looksLikeApp(dir, io) {
+    const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
+    if (null === pkgRaw)
+        return false;
+    const configs = [
+        ...VITE_CONFIG_CANDIDATES,
+        ...ELECTRON_VITE_CONFIG_CANDIDATES,
+        ...NEXT_CONFIG_CANDIDATES,
+    ];
+    if (configs.some((c) => io.exists(`${dir}/${c}`)))
+        return true;
+    // `next.config` is optional in Next, so the dependency list is the other half of the signal.
+    if (APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`)))
+        return true;
+    // And the honest third: an app somebody can SERVE. Asking only for a bundler missed every app
+    // built on anything else — Remix, Astro, a plain node server — and in a monorepo missing it means
+    // init never redirects, wires the ROOT, and reports ✓ for files nothing compiles.
+    //
+    // A monorepo root has no dev script by design, and a package that can only be BUILT is not the app
+    // somebody is working in, so this stays a filter rather than matching every directory.
+    return hasDevScript(pkgRaw);
+}
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export function findWorkspaceApps(io) {
+    const found = [];
+    // A workspace DECLARES its packages; `['apps','packages']` was a guess that missed a real repo
+    // with three Next apps at web/, admin/ and space/ — and missing them meant init ran against the
+    // root and reported ✓ for a file Next never compiles. See workspace-apps.
+    const pkgRaw = io.readFile(PACKAGE_JSON);
+    let pkgWorkspaces;
+    try {
+        const parsed = null === pkgRaw ? undefined : JSON.parse(pkgRaw);
+        pkgWorkspaces =
+            'object' === typeof parsed && parsed !== null
+                ? parsed.workspaces
+                : undefined;
+    }
+    catch {
+        pkgWorkspaces = undefined;
+    }
+    const parents = workspaceParents({
+        ...(null === io.readFile(PNPM_WORKSPACE)
+            ? {}
+            : { pnpmWorkspace: io.readFile(PNPM_WORKSPACE) ?? '' }),
+        ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
+        topLevelDirs: io.listDirs('.'),
+    });
+    // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
+    // its children rather than assuming one level of nesting.
+    for (const parent of parents) {
+        if (looksLikeApp(parent, io))
+            found.push(parent);
+        for (const name of io.listDirs(parent)) {
+            const dir = `${parent}/${name}`;
+            if (looksLikeApp(dir, io))
+                found.push(dir);
+        }
+    }
+    return [...new Set(found)];
+}

package/dist/workspace-redirect.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Workspace redirect: when `init` is run at a monorepo ROOT, wire the app rather than the root.
+ *
+ * Split out of `run.ts`, which sits one line under the 1000-line backstop — every init change that
+ * touches the orchestration now trips the cap before it can be reviewed. This is the part of that
+ * file that answers a single, separable question ("is the app somewhere else, and where?"), so it
+ * is the seam that costs nothing to move.
+ *
+ * `runInit` arrives as a parameter rather than an import: re-entering init is the whole point of a
+ * redirect, and taking it as an argument keeps this module a leaf instead of forming a cycle with
+ * the file it was cut from.
+ */
+import type { InitIo, InitOptions, InitResult } from './run.js';
+/** Re-enter `init`, scoped to one directory of the workspace. */
+export type RunInit = (options: InitOptions, io: InitIo) => InitResult;
+/**
+ * When the current directory is a workspace root with no app of its own, wire the app instead of the
+ * root. One candidate is wired silently (there is nothing to ask about); several are listed, because
+ * guessing which app someone meant is worse than one line of output.
+ * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
+ */
+export declare function redirectToWorkspaceApp(options: InitOptions, io: InitIo, pkg: unknown, runInit: RunInit): InitResult | null;

package/dist/workspace-redirect.js

@@ -0,0 +1,97 @@
+/**
+ * Workspace redirect: when `init` is run at a monorepo ROOT, wire the app rather than the root.
+ *
+ * Split out of `run.ts`, which sits one line under the 1000-line backstop — every init change that
+ * touches the orchestration now trips the cap before it can be reviewed. This is the part of that
+ * file that answers a single, separable question ("is the app somewhere else, and where?"), so it
+ * is the seam that costs nothing to move.
+ *
+ * `runInit` arrives as a parameter rather than an import: re-entering init is the whole point of a
+ * redirect, and taking it as an argument keeps this module a leaf instead of forming a cycle with
+ * the file it was cut from.
+ */
+import { join } from 'node:path';
+import { detect, Framework } from './detect.js';
+import { findWorkspaceApps, PACKAGE_JSON } from './workspace-apps.js';
+import { chooseWorkspaceApp, withoutTrailingSlashes } from './app-choice.js';
+const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` inside the one you want:';
+/**
+ * When the current directory is a workspace root with no app of its own, wire the app instead of the
+ * root. One candidate is wired silently (there is nothing to ask about); several are listed, because
+ * guessing which app someone meant is worse than one line of output.
+ * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
+ */
+export function redirectToWorkspaceApp(options, io, pkg, runInit) {
+    if (true === options.redirected)
+        return null;
+    const rootFiles = new Set(io.rootFiles());
+    const here = detect({
+        pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
+        configFiles: rootFiles,
+        lockfiles: new Set(),
+    });
+    // `--app` is an INSTRUCTION, and it is read before the guess below. The guess answers "where is
+    // the app?" for somebody who did not say; when somebody said, there is nothing left to infer.
+    //
+    // It used to be read after, and the check underneath returns early for any directory that looks
+    // like an app — which a JS monorepo ROOT does, because shared tooling puts `vite` in its
+    // devDependencies. So on a real pnpm+turbo monorepo (measured on nuclear, a Tauri v2 app at
+    // product scale) `reticle init --app packages/player` silently ignored the flag, installed the
+    // SDK into the root's package.json, wrote `.reticle.json` and a whole `src/reticle-dev.ts` into a
+    // repository root that has no `src/`, left `packages/player` untouched — and reported three ✓ and
+    // one ⚠. The one flag documented for this shape wired the wrong directory and said it worked.
+    //
+    // Existence is the test, not membership of the discovered list: discovery scans conventional
+    // directories, and somebody who names a path knows their own layout better than the scan does.
+    const named = options.app === undefined || '' === options.app ? undefined : options.app;
+    if (named !== undefined) {
+        const wanted = withoutTrailingSlashes(named);
+        if (io.exists(`${wanted}/${PACKAGE_JSON}`))
+            return enterApp(options, io, wanted, 'Wiring', runInit);
+        io.print(`--app ${named} does not name a directory with a package.json in it.`);
+        return { ok: false, applied: 0, manual: 1 };
+    }
+    if (here.framework !== Framework.HTML)
+        return null; // this directory IS the app
+    const apps = findWorkspaceApps(io);
+    // An explicitly named app answers the ambiguity. Refusing to guess is right, but "re-run inside the
+    // one you want" is not something a script, a CI step, or an agent that cannot change directory can
+    // act on — so the refusal was a dead end for exactly the callers most likely to hit it.
+    const chosen = chooseWorkspaceApp(options.app, apps);
+    if (!chosen.ok) {
+        io.print(chosen.message);
+        return { ok: false, applied: 0, manual: 1 };
+    }
+    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)
+            io.print(`  ${a}`);
+        io.print('');
+        io.print(`Or name one without changing directory:  reticle init --app ${apps[0] ?? '<dir>'}`);
+        return { ok: false, applied: 0, manual: apps.length };
+    }
+    return enterApp(options, io, target, 'No app in this directory — wiring', runInit);
+}
+/**
+ * Re-enter `init` scoped to one directory of a workspace.
+ *
+ * One implementation for both routes in — the app somebody NAMED and the app discovery found when
+ * nobody did. They differ only in the sentence printed; scoping the io, moving the cwd and keeping
+ * the agent root has to be identical for both, and was worth having twice for exactly as long as it
+ * took to get one of them wrong.
+ */
+function enterApp(options, io, target, lead, runInit) {
+    io.print(`${lead} ${target}.`);
+    io.print('');
+    return runInit({
+        ...options,
+        cwd: join(options.cwd, target),
+        redirected: true,
+        // 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,
+    }, io.scoped(target));
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@reticlehq/init",
+  "version": "2.14.0",
+  "description": "Reticle project scaffolder — detects the framework, writes the config, patches the build and registers the MCP server. The build-time half of `reticle init`.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@reticlehq/core": "2.14.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Reticle contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reticlehq/reticle.git",
+    "directory": "packages/init"
+  },
+  "homepage": "https://github.com/reticlehq/reticle#readme",
+  "bugs": "https://github.com/reticlehq/reticle/issues",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "mcp",
+    "ai-agents",
+    "scaffolding",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "lint": "eslint src",
+    "test:unit": "vitest run src --passWithNoTests",
+    "test:coverage": "vitest run src --passWithNoTests --coverage.enabled --coverage.provider=v8 --coverage.reporter=text-summary --coverage.include='src/**/*.ts' --coverage.exclude='src/**/*.test.ts'"
+  }
+}